Kong Kong Summit 2020, 26 Dec 2020

Previous Meeting

Next Meeting

⏯

youtube image

►

From YouTube: Accelerating Software Quality and Velocity with Spec Based API Development | Kong Summit 2020

Description

All organizations want software development to improve quality and velocity. Optimizing the development workflow around APIs has proven an important part of achieving these outcomes. Organizations that shift from ad hoc API development to spec-based API development based on standards such as OpenAPI and GraphQL are leading the way. In this session, Kong engineers will share how Kong can help.

You will learn how to:

- Enable API implementers to quickly build quality interfaces and make them available for reuse
- Enable API consumers to easily make use of interfaces available to them for their development needs
- Gain the most value from the Kong portfolio of products, including - Insomnia Core and Insomnia Designer, Kong Gateway, Kong Vitals, and Kong Developer Portal

A

Hello, everyone. I am vikas vijandra, a solutions engineer at con.

B

And I'm a pender a software engineer on the insomnia team.

A

And today, in this session, we are going to be showing you how kong can help accelerate software quality and velocity with spec based api development.

A

As you know, most say, software's or applications today are api, driven and hence spec based api development is really important and all organizations with software development lifecycle want to improve quality and velocity optimizing. Your development, workflow around apis has proven an important part of achieving this outcome.

A

So in this session we are going to not only take you through an overview, but also show you a demo of how you can do that with insomnia and kong.

A

Together before we go into the demo, um I would like to set some context and then share our experience or point of view of what an api development end-to-end life cycle would look like.

A

At kong, we've been working with a number of customers uh to look at what are the key lifecycle stages but, more importantly, I think there's one unique thing that we have recognized. Learning from our customers, which is automation, is the first class citizen as part of the life cycle.

A

So if you look at the different lifecycle stages here as it builds out, there are three primary categories. So if I bring your attention to the screen here um in the middle, so that's where you start with designing an api, adding your tests, then managing them and then say productionizing it onto the gateway. So all of those are say key first steps, but at the same time you can have a team of people or developers working on your apis say.

A

One of um a key steps would be to mock an api, uh because what that allows you is to not having to build an implementation and then make that api available to your consumer.

A

So that's where mocking comes in and then you add, in other things that are important for api management like securing your api and protecting your backend apis.

A

Once you have all of that done, then we move on to the left-hand part, which is about consumption, so consumption of apis could be a web application developer or a mobile app developer, or it could be just a third-party api consumer, so any of them then, can go on to develop a portal to consume those apis seamlessly and keeping in mind all at.

A

As all part of all of these stages, you may or may not have an active api implementation built out and that's where your software development life cycle should be very consistent with making the implementation um go hand in hand with what is exposed by the gateway.

A

So as part of this session, we'll not touch upon all of these life cycle stages, however, focus on just a few of them. So if you look at it, the highlighted ones are what you're gonna see and automation is something that will also come back and summarize on as part of the demo.

A

So without further ado, let's try to drill down further into what this workflow looks like and before I do that. I want to also call out uh another key point, which is primarily uh customers and based on again uh the feedback that we have got from customers is. There are two main approaches to how you do say: api development and how you go through a developer workflow.

A

The primary one has been code driven approach or an ad hoc approach, which is you start building your say apis or softwares, and then worry about the specification later on. I think that is great. However, as you start scaling, as you have more and more developers coming on, what we see is it may not scale as well and that's where spec based api development comes in, which gives you both velocity and an ability to have a focus on software quality.

A

So another key point here is what we have taken as part of the workflow with kong. Would be to work on one single source of truth and that really comes down to an open api specification as you can see on the screen. So let me call upon open there to give his perspective as an engineer on what this workflow would look like.

B

Thanks vikas, so as an engineer, I'll start with with an open api specification with an insomnia designer.

B

And insomnia designer will then help me to write the mocks and unit tests against the routes and the configuration in that specification.

B

And that enables the api developers and the ui developers to to build those aspects in parallel with the specification and the marks and tests all going into a get repository and then again, the code can also exist within git and be piped into an automation, icd pipeline now as part of the ci cd. You would also want to validate the api. That's been built um against the tests that were written within designer at the start.

B

um So to enable this, we created um a companion, cli called inso that allows you to run the insomnia designer unit tests within a ci environment, sticking with the theme of the open api, spec being the source of truth.

B

We can also configure cong through that and enso will generate declarative configuration for kong, including any routes and upstreams and plugins and feed that into an automation pipeline, which can then be published out to the kong gateway or to the developer portal.

A

That's great, so, let's move into the demo, shall we.

B

Yeah for sure, so what we'll do is demonstrate some parts of that workflow.

B

um I will assume the role of an api engineer who is laying out the groundwork for a pizza ordering api first, we'll start with designing the specification and unit tests within designer and then we'll move on to see how kong can help accelerate the api development process and then briefly touch on how we can automate that in a ci environment using enso, exciting cool.

B

So what I have here is um there's a document within insomnia designer an open api, 3 specification for my api, and currently this has an upstream and it has just one path, which is to return all orders to fetch all the orders.

B

So insomnia will automatically uh ingest this re, this uh specification that I've got and it will generate all of the requests for me to make queries against against my configured servers.

B

So if I hit send here, we can see that we receive some data back from the api.

B

We can now write some unit tests against that so jumping to the testing tab. What I've got here is a simple test written that hits that request that we just saw it makes sure that we receive a 200 back and it's a valid response, and it ensures that I receive some number of orders, so I can run that test and we see that it's passed and that's great.

B

So now. What I want to do is add a new route, for instance, so I'll collapse, this one and here's one that I prepared earlier, which is to get the active order, which is just a get method.

B

So once again, designer will automatically generate the request for me against that, against that new endpoint and because I haven't actually implemented the back end for that I've just got a blank blank path there I just get an empty response back now again, I can write a test for this as well, just to make sure that I receive a valid response. So I've got one written here and right now it just checks that again I received 200 back and testing that we see that it passes.

B

So what we've done. There is just the first aspect of introducing a new specification and introducing unit tests within designer.

B

Next up, because I don't actually have- I haven't actually implemented the api yet and it might be more complex than simply returning a single order.

B

What I, what I can do is consume one of the plugins within kong for mocking, so to enable that I simply just uncomment that which is just adding a plugin directive within that route, that I created to say that telcon to return a mock result.

B

Looking at the config that's been generated the declarative configuration. We can see that under the new path that we created, that the mocking plugin has been enabled for cong.

B

So at this point, what we can do is I'll jump into the terminal and we can run a command for inso, which is the companion cli to generate the configuration for that api.

B

So what we see here this is the same configuration that we just saw within the application, but through a through a command line.

B

I can take that and I can pipe that response into deck, which will update kong for me, which will update my local instance of kong, and we see that the mocking plugin has been enabled for the route that we created.

B

So at this point we can jump back into designer and go to the debug tab and for that same request again, if I make a request against my local environment, we see that we receive. We get some data back now and looking at the headers, we can see that kong has actually responded to that.

B

Even though I haven't actually made any changes to my api and now that we've got some data, some valid data coming back, we can expand on our unit test that we wrote and make sure that when we're loading the active order, we receive make sure that we receive one order and that order has the expected properties on it. And again, if I run that test, we see that it passes.

A

That was quick, isn't it that's nice, so would would we be able to add any kong plugin in this manner.

B

um Yeah we can so the the x-con plug-in directives uh support anything, um but that can also extend to the fact that we can also smartly apply some plugins.

B

So, for instance, if I wanted to add some authentication into my into the new route that I added, I can make use of security schemes, which is a part of the open api, spec, so I'll, add a new security scheme for api key and that will that will say that I am expecting an api key to exist in the header for the request and then.

A

I can enable.

B

That against the route.

A

Yeah, that's so cool looks like it's already set up where developers can start using this in an enterprise manner.

B

Yeah, so what I've done here is I've just enabled um the api key security scheme against that new route and looking at the config that's generated for cong. Again, we see that the key auth plugin has now been enabled against that new route.

B

So we can go ahead and update kong. The same way we did before and we see that the key auth plugin has now been created against that route, jumping back into designer I'm going to the request again designer, because it will ingest the specification, because I added a key auth header as part of the specification.

B

It's automatically added the header for me here. What I did previously was added or generated an api key against my local kong environment, which we can send, and we see that it's sending fine. Now, let's say that. I remove that key and I don't send it. um I receive a 401 unauthorized back and if, if someone has made any changes that, like inadvertently removing the api key, for instance, the unit testing will pick it up, because now this test has now failed because I expected to receive 200 back, but I received.

A

401. looks too easy for me, so um I'm curious, so you've you've been able to apply plugins and policies right within open api specification onto con right. So can we verify this hong kong? Please.

B

Yeah for sure, so what I've got here is that same api that I created with with my upstream. um We can see the responses that we've made recently the request that we made recently and the two routes, so all orders and active order and again against the active order. We see that we've got two plugins enabled the same way that we enabled them through the specification.

B

That's wonderful.

A

That's that's really modern api management in a declarative manner,.

B

For sure cool, so that concludes the second part, which is um effectively helping you to accelerate the api development process, because what I've done is enabled authentication and enabled mocking without actually touching my api, my api implementation itself and, lastly, let's jump into the automation step of how we can automate uh much of this process, so you'll notice that this document and all of the unit tests have actually I've actually got it synchronized into git.

B

So if I jump into that get get repository, I have a workflow enabled here and I'll just step through the actual steps of the workflow, and we will make this repository available as a template and an example to use, but looking through the steps here, it's simply doing a validation of the specifications or running linting. um It's deploying that specification to the dev to the kong developer portal. It's deploying my upstream so my backend api.

B

However much of it that I've got implemented, um it's generating the declarative, config and updating pong and then it's running unit tests against that entire configuration. So this is the entire the same workflow that we ran locally but running in a ci environment. So if the developer, when they're introducing an api or introducing a change to the back end, was to inadvertently make any sort of unexpected changes this this github or this ci workflow, can detect that and fail any of the steps and prevent emerge into your main branches.

A

Oh, that's cool as well. I'm curious and have another question here, um so it says deploy to dev portal. So what is it doing there and can you show me uh what comes up on the portal when it does that.

B

Yes, so it's actually uh publishing that to the um to the developer, the catalog.

A

B

A

B

A

B

Also, our pizza or pizza api without two routes, so anyone that has access to this can now go and consume it from here.

A

Nice, thank you.

B

Cool, so let's recap um so we we went through the design steps which was uh writing the open api spec and introducing unit tests within designer and then accelerating the development process by enabling and configuring plugins through the specification for cong and then automating that that whole process with the ci cd workflow.

A

Excellent, thank you so much uh open there for that great demo there. So if I want to summarize everything that we saw so far in the demo, it really comes down to what, as kong, we see the combined value of insomnia and kong together and when you use both together with the tooling that we have provided with integrations, what you get is higher quality and velocity with your software development, also as part of the lifecycle stages.

A

If I want to review what we just did um and from our point of view, what an a seamless api development lifecycle would look like, is you start with the design to quickly build and collaborate based on specifications which is open api spec today, you quickly add mocks to your api, so you don't have to worry about building out implementations, which then makes it available directly on dev portal, with the tooling that there is to publish to their portal.

A

So the key thing there would be as soon as an api with a mock is on the portal it's already discoverable and then ready for anyone to reuse, which is what you would like to do when working as a team rather than building out new apis, and once you do that the development team, which is the api implementer, can either work in parallel or can work after the spec has been reviewed to start building on the implementation and then the rest of it is the consumption side of things which you can make.

A

It happen through dev portal. um And finally, um as you can see, automation is always a first class citizen, because you can start automating using either inso or any of the other cli tools that we have right from day one. So that's, basically um the key takeaways from this session.

B

Awesome and lastly, I'd just like to mention that, while designer itself is still fairly new, it does build on top of insomnia core, which is a hugely popular rest and graphql api client, core and designer. They both have a shared code base, which means there's shared improvements and any contributions and plugins that the community creates they. They use they're used across both applications.

B

It also builds on top of the strong kong and insomnia open source communities and there's a really quick feedback loop that we take into account when we're building out new features and experimenting with with new aspects of the program.

B

Designers. Seen a lot of uh a lot of awesome adoption of over the last couple months, since we've released it um and there's been a lot of feedback that we've already taken in.

B

Cool and with that, that's a wrap. So thank you all for attending this on and we can now take.

B