Kong Kong Tutorials, 15 Jun 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Creating an Interactive Developer Portal with GraphQL

Description

In this tutorial, you'll learn how to get to the next level of API documentation using Kong Developer Portal with GraphQL. Learn more about Kong Konnect and start a free trial: https://bit.ly/3vDuUBz

1:00 - What You’ll Need
3:30 - Create a Template
5:26 - Add Content
6:27 - Edit Title
7:55 - Add an API URL
9:04 - Copy Example Code from GraphiQL
11:34 - Test the Interactive Developer Portal
14:08 - Add a Link to the Navigation

In my example, I’ll be using Kong Konnect Enterprise Version 2.4, but the version number does not really matter. I also configured my workspace with one service that points to a Star Wars API endpoint with a GraphQL interface (swapi-graphql.netlify.com).

We’ll also be using an open source tool called GraphiQL for interactive documentation of a GraphQL endpoint. With GraphiQL, we’ll see requests, responses and automated generation of documentation based on the endpoint.

Read the full tutorial blog post: https://bit.ly/3pWR9kr

Contact us if you have any questions as you’re getting set up: https://support.konghq.com/support/s/

Once you’ve set up Konnect and Okta, you may find these other tutorials helpful:
• Automating Your Developer Pipeline With APIOps (DevOps + GitOps): https://bit.ly/3yPEsMa
• Service Design Guidelines Part 2: API Versioning: https://bit.ly/3pH0jB6
• “Gateway Mode” in Kuma and Kong Mesh: https://bit.ly/3ixLeQQ

#GraphQL #DevPortal #APIs #devcatalog

A

Today, we will extend the developer portal,, which comes out of the box with a catalog.

A

With some more functionality using templates., so what do we want to achieve?

A

first thing: is we see here a standard developer portal that we have a catalog which is.

A

Based on restful apis., so you can do all the typical things with a restful api.

A

you can can go, ahead,, filter them and then try them. Out.

A

You have all the different kinds of trying things out and execute the calls.

A

This is a very nice tool in the restful world of apis.

A

But we want now to go to the next level of apis.

A

And this is graphql., so we want now not only to have this kind of documentation,, but also an interactive way.

A

Of speaking to this graphql endpoing within our developer, portal.

A

So what do we need and what's the setup we have here today up and running.

A

Well,, I have here up and running kong enterprise version 2.4,, but the version does not.

A

Really matter., the only thing which has been configured next would enable the developer.

A

Portal here on that workspace is, I already have put in one single service.

A

You can see it's one single service and this one single service points to star wars, api.

A

Endpoint with a graphql interface., that's an example: I have put in here.

A

which, we'll from now on, to work with the documentation.

A

So when it comes to documentation of graphql,, there is a best practice that you can do it.

A

In an interactive way- and there are some tools available- that you can use.

A

We will today look at a tool called graphiql open source system,, which we can use for.

A

Interactive documentation of a graphql endpoint.

A

And you can see if you scroll down a little bit,. It looks like this as a tool.

A

You can see the request, response and also an automated generation of documentation based.

A

On the endpoint. and now we want to get this into our dev portal for a much nicer.

A

Experience for developers to play with an backend system.

A

So how do we do that?, let's go step by step and let's have a look at how we can extend this existing developer.

A

Portal., this dev portal is just the default one coming out of the box.

A

So if you go here in our management of the system,, we will see here in our workspace that.

A

We have here the whole dev portal section..

A

We will focus today on the editor, because you want to change the layout and we want to.

A

Add some functionality.. So let's have a look in here and let's have a look. What we will find here in the.

A

Different sections. we have, on the upper part the general configuration file,, which holds, for example, the.

A

Title of the dev portal that holds the whole menu structure.

A

Then we have a section of the contents.

A

All the pages here. for example,, if you just click here,, you see, there's also the homepage of the dev portal.

A

And there are all the other pages here.

A

we have here. The restful api, open api based specifications,, which we have seen already in.

A

The catalog that we have here.

A

the themes and the themes we want to actually use.

A

So let's have a look on how we can create something here from scratch that we get a new.

A

Page into the system,, which we can use as a basement for our documentation of a graphql.

A

Endpoint. so the first thing that we say, we need to have our own template.

A

And let's have a look here in the same sections which we have here, layouts.

A

There are all the different layouts here which come out of the box with kong, enterprise.

A

And you can see,, for example, here,. That's the template for the homepage and here and we.

A

Will create our own template here with doing something very lightweight at the beginning.

A

So, let's add a new template here by designing a new file.

A

It should be in the theme., you also have it in the base and the layout folder,, and we will call it graphql.html.

A

So we're getting here now a very lightweight template in the beginning.

A

Let's do something a little bit more in here..

A

Let's say we want to have here also some header and footer attached to it.

A

So how do we do that? well,? Let's have a look at the homepage,, how we can just borrow here.

A

Those things we can go to the homepage.

A

That's how it looks like you need to go here and then we get in here.

A

Headers and footers. hmm., let's just borrow from what we already have.

A

Go to graphql. put it in there and get rid of this part here where you have to dev class,.

A

Main class and all the things., so you only want to be here in the setup page of the page in here.

A

So, let's remove all the clutter and just say here for the beginning: "hello world" have.

A

A

now that we have a template.. This template does not do anything so far.

A

The next thing is now that we need to figure out. How do we get something here and a.

A

System that will also use the template.

A

So, let's remember the name that is called graphql.html.

A

So we need to have content which references this template.

A

So we go and you file this time. You want to have content.

A

The content section.

A

That's the star wars, api. We have already seen here as an example.

A

So let's create that file. and if you look at that file, you have your title text..

A

So let's call this "star wars".

A

And to layout, that's the name of the layout. We have just a referenced down here.

A

So we just say the layout is called graphql.html, the one we just created.

A

So, let's save those changes., and here we are already are.. You have now a template being rendered here and we have here now the "hello world,", which.

A

We have put in there to make it happen that we have this"hello world" in here.

A

So, let's do something more fancy., let's say we have a title,, wouldn't it be nice if that title would be somehow being.

A

Visible, instead of this "hello world" stuff?.

A

Let's go ahead., let's go out to our template.

A

and in that template you can embed any data, which is in that yaml file. You've just seen.

A

., so you can once again just borrow something..

A

You can have a look here.

A

And then I have this curly brackets.

A

Let's just do that. instead of "hello world,". We want now to have here "{page.title}".

A

That's the parameter. We have defined.

A

Save. now it's rendering star wars like is in the title.

A

Upload the content here and say it's now about "may the force.". We are.

A

Getting dynamic rendering of content in here, and you can put anything in that yaml.

A

Structure., so let's do one more thing., let's go ahead and, let's add a url.

A

And we will take the url out of the already existing backend.

A

I've already proxied it here using kong, the url of our star wars. Api backend is localhost: 8000/swapi.

A

So far, we have not done something., we just have put some data in there and we could also just displayed it.

A

We could go ahead and say, graphql and after h1, I want to show this one here, like once.

A

Again, curly brackets, page dot, url.

A

A

save. and now we have the url written in here.

A

Well, nice, that it works,, but not really what we're looking for.

A

We are looking to put something in place that is much more interesting.

A

We want to have some interactive stuff., so let's go ahead and do here this graphql.

A

So this graphql we have in here is a javascript interface and in kong you can do anything.

A

In the templates. this can be any kind of content., it can be pure html., it can be css,, it can be javascript., so you have the full accessibility,, whatever you can think. Of.

A

So let's have a look at this open source project and let's see.

A

There some examples.

A

yeah,, you can also download the application, but here' one hosted one.

A

Perfect., that's an example.

A

This is how you can use it.

A

perfect.. Let me just copy and paste all that stuff in here.

A

Go to our template.

A

Instead of all this clutter in here, yeah,- let's put in here, if you say this is not a.

A

Page title anymore,, boom.

A

And for you not to have this whole stuff,, we have just copied in here.

A

As you see already on the website, we do not need the whole head section from the html.

A

That's already done by our templates.

A

Let's remove that stuff and removing just closing html.

A

Ok,, let's see.

A

We have css in place, some javascript in place.. Let's save the changes.

A

Boom. we already have now a working graphql within our browser.

A

?, that's not really happy with where the url is coming. From.

A

Ok,, it's trying to render this one.

A

Just not working on my pc.

A

reasons,, but we already have an api,, so we can just say: localhost 8000/,.

A

Save. and now something happens.

A

But before we have a look here, how this now renders in the real world,, it would be much.

A

Easier or nicer, if you would not put that here in a hard coded way.

A

And remember, we created a variable for that, so we can just put it in here.

A

Ok, so let's now put in here what we already have in here.

A

This time,, I will not use the two curly brackets.

A

this time I will use a slightly different syntax..

A

The reason for that is that we do not want to encode this in some ways..

A

We all want to have the full url available for the javascript.

A

So we have many options to parse our data., so it's page dot url like we have done before.

A

Save the changes.- and you see it's now, rendering as expected.

A

Great., so we now have something which seems to be working.

A

Let's have a look in the dev portal to find an example here.

A

And we have now here a running version of graphql in our browser.

A

There are some minor quirks, which, if I want to make nicer, I can,, but it's already fully.

A

Working., let's have a look.: let's move this here..

A

This is in our dev portal.. We now have this interactive, very nice stuff of graphiql.

A

Well,, you can see all the documentation. we see, there's an all films, endpoint. ok,. What's that., there's a films collection, there.

A

Ok,, it's all the things I have already been using as an example..

A

Let me just play that one and get a response back from the backend system.

A

Comes from graphql., we here, films title.. What else do we want?? Let's say we want also the director and then we can just go ahead here and say: director.

A

I see autocomplete auto generated and now I know all about george lucas.

A

So very nice interactive way to work with an api.

A

You get here, autocomplete, multivariable., so all the bells and whistles you get from the nice graphical endpoint just put into my.

A

Dev portal, with those minor steps., I just in fact copied javascript and some xml into my template.

A

And now I have the ability to put as many pages based on that into my system.

A

So, there's nothing stopping me from going ahead.

A

and I want to have a second one.. Let's just see how that one looks like., I can just say I want to create a new content. File.

A

This one is another graphql.

A

Once again, it's graphql.html.

A

Then I could say that's a different graphql endpoint.

A

And then we would have to specify some kind of http, url and so on.

A

So you only have to create a template.

A

Then you can have as many of those in your system as you want.

A

So last thing,, not if you have done all those things is about nice- that we have it.

A

But if I look at my dev portal to the homepage,, it's linked nowhere.

A

You simply cannot find that it's even existing and as everything in kong is declarative.

A

So also the whole navigation is all the links are. You can have marked down pages to make.

A

Overview sites, and so on. in this example, you have seen that we have here, the whole menu structure in here.

A

So we have the whole list of all the menu and you'll see it as catalog, my apps,, all the.

A

Sections you see up here. if you want to just extend it, it's easy, since everything in kong is declarative.

A

You can do much more fancy. Things,, like you, can make buckets dependent on.

A

The authentication, role of success.

A

just for this example,, which I say that's enough.,.

A

Go to our dev portal.

A

reload here and see. Now we have another endpoint where you can just click on it.

A

Documentation. or you could create an overview page where we list all of them.

A

The opportunities are endless.

A

This, for example, my vote to stop it now. Here just gives you an a first feeling how.

A

Extensible and how easy it is to extend the the kong developer portal with, in the end, a.

A

Quite complex scenario. we want to have an interactive tool which does javascript magic, autocomplete and all.

A

Those things. and you just need to have those snippets.

A

Api and then other tools say they're all there out in the world.

A

Whatever you prefer., you can put them in there., create your own template, so it's only doing once.

A

and then remember,. The only thing if you create a new backend system and new graphql,.

A

You need to have just one such file.

A

The only real important point is the url is where it's located.

A

And the whole rendering is done in a complete way and an automated way.

A

So thank you for listening. and if you have more questions,, feel free to contact us.