Service Design Guidelines Part 1: OpenAPI and Kong

Introduction

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.

APIs or Services?

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.

Rule of thumb

You create a new Kong Service to:

• Define a backend application or a micro-service as a single string or by specifying its protocol, host, port and path individually
• Provide access to a specific user or API provider team
• Utilize a Domain Driven Design approach and hence create a separate service for every subdomain
• Specify individual retry, timeout, certificate or tagging configurations as shown below

Figure 2 – Service Creation in Kong

You create a Kong Route:

• For every API method or URI path
• Specify the URI version in it (eg: /api/v1/account)
• Follow API guidelines to ensure you maintain consistency
• Utilize the power of regular expressions in the path as explained in the documentation here

Conclusion

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!