Build with Confidence: Beta API Specs Available Now

Few things are more frustrating than encountering a product with either no documentation or worse: documentation that leads you astray. When it comes to developing APIs, schemas typically define how requests and responses are formatted and guide how clients and services exchange data. Commonly, schemas aren't used to generate documentation or software development kits (SDKs), allowing them to become stale and inaccurate.

At Kong, we're committed to a different approach — having a single source of truth for our schemas. These schemas power both our code and our documentation, guaranteeing its accuracy and timeliness.

As a step forward, we're excited to announce the availability of our beta OpenAPI specifications for both the Kong Gateway Admin API and Konnect Runtime Groups configuration API. These specifications are designed to provide everything you need, all presented in a standardized format you’re already familiar with. The best part? They effortlessly integrate with your existing toolchain.

What does this mean for you?

• SDK Generation: The API specs enable more efficient SDK generation, ensuring you can interact with the Kong Gateway API regardless of your preferred platform or programming language.
• Kong Insomnia Integration: The API specifications seamlessly integrate with Kong Insomnia, or another API development platform, allowing you to test and interact with our APIs in an easy way.
• Version comparisons: With our APIs hosted on the Kong Konnect Dev Portal, you can compare different versions of the API specs, so you can track changes and updates effectively.
• Validation testing: You can now create automated tests that validate endpoint functionality. This enables you to take a proactive approach to testing related to the Kong Admin API or Kong Konnect.

Why now?

In an ideal world, all of our APIs would follow a design-first approach where the OpenAPI specification is the source of truth. Whilst this is true for our new Konnect APIs, Kong Gateway is a long-running open source project that treats Lua schemas as its source of truth.

Lua schemas being the source of truth with handwritten markdown documentation meant that API documentation lagged behind code changes, leading to confusion and frustration both internally and externally. To address this, we decided to make the Kong Gateway code the single source of truth for our API documentation and generate JSON schema entities from the code. Every endpoint, parameter, and response is now derived from and defined in the Kong Gateway code. This is to ensure that our API remains accurate and up to date.

Using the code as the source of truth didn't mean that we got everything for free. API documentation that's missing descriptions about what each field in the API is used for is almost useless. This led us to upgrade the underlying Lua schemas to contain description fields for every entity and create a generator that extracts all of the parameters, constraints, and descriptions when generating an Open API spec.

While our specs are robust and reliable enough that we're using them internally, we're still actively working on the generation process. But we wanted to give everyone access to these tools to empower them in the Kong ecosystem. Hopefully, this encourages you to explore, test, and provide any feedback related to these specs so that we can improve them to the point that they meet the same standard as the rest of our products.

Our long-term vision is to move to a design-first approach and treat OpenAPI as the source of truth for Kong Gateway. However, there are a lot of benefits from having a spec (even one generated from code) and we don't want perfect to be the enemy of better.You can find the specs hosted on our Docs site, and if you want to get started in Kong Insomnia, you can use these dedicated Kong Insomnia links for Kong Gateway and Kong Konnect.

If you spot any bugs, please let us know by emailing team-docs@konghq.com. And if you build anything cool with the specs, come tell us in the Kong Community Slack.