See what makes Kong the fastest, most-adopted API gateway
Check out the latest Kong feature releases and updates
Single platform for SaaS end-to-end connectivity
Enterprise service mesh based on Kuma and Envoy
Collaborative API design platform
How to Scale High-Performance APIs and Microservices
Call for speakers & sponsors, Kong API Summit 2023!
3 MIN READ
We are in the midst of an explosion of APIs and microservices. For some, the first instinct of creating an API is to get down to building one. Some level of planning will help manage the quality of APIs when working within a team.
In this series of blogs, we will be sharing some guidelines on service design while working on API projects with Kong. Let us start by focusing on how to go about designing APIs that end up as entities that the Kong API Gateway runtime understands.
Kong is the world’s most popular open source API Gateway. The world-wide millions-strong developer community and over 250 enterprise customers have been running API workloads since its inception on the back of Mashape’s success. For the curious, have a look at this story on how Kong was founded. Along the way Kong evolved to not just be focused on APIs, or just do API Management. Kong manages any service, beyond RESTful. The service object, introduced more than two years ago in 0.13. is a dynamic entity capable of representing any endpoint we can imagine.
Fast forward to the current day and Kong allows Full Lifecycle Service Management for services that run on multiple protocols – HTTP, gRPC, GraphQL, TCP, etc. Hence, designing APIs or Services starts with one key entity in Kong – A Service.
What makes a Service/API in Kong?
Let us look at the Service object definition in the Kong documentation:
Service entities are abstractions of each of your own upstream services. Examples of Services would be a data transformation microservice, a billing API, etc.
If we want to bring in a real world example, let us load an existing API design spec – Account API – as per Open Banking OpenAPI Specification into Insomnia Designer:
Figure 1 – Insomnia Designer Preview Mode
In the above example, we could define Accounts and Balances as one or potentially two separate service objects. But, the leading question would be how do you represent the API methods?
You probably got a hint from the picture above, if you know the Kong basics, that they are configured as Routes. If we go back to documentation to ensure we understand the concepts well:
Route entities define rules to match client requests. Each Route is associated with a Service, and a Service may have multiple Routes associated with it. Every request matching a given Route will be proxied to its associated Service.
To summarize from an API Designer point of view:
Table 1 – API Consumer and API Provider views.
You create a new Kong Service to:
Figure 2 – Service Creation in Kong
You create a Kong Route:
In this first part of the blog, we looked at how you can design your APIs/Microservices in an API Designer, such as Insomnia Designer, and then configure the relevant entities such as Service and Routes. If you are in the mood to try out something fun, have a look at the declarative config plugin in Insomnia which automates the process of generating Service & Routes from Open API Spec. Check it out and let us know how you like it!
Try out Insomnia Designer