Automating API delivery: 6 principles of APIOps

The book "Automating API Delivery: APIOps with OpenAPI” presents the six principles of APIOps:

1. Embrace an API-first approach to API development. API-first is an iterative methodology, also known as design-first, specification-first or contract-first, that involves crafting an API definition file and gathering feedback on its design before coding begins. An API definition file (for example, an OpenAPI file) is a machine-readable file that defines the structure, functionalities, and endpoints of an API. Iterating on the design of the API definition first and getting feedback on it before implementation ensures all stakeholders align on the API's purpose and functionality, reducing rework and inconsistencies.
2. Treat API definitions as code by storing them in a version control system like Git. This approach provides an audit history of changes and facilitates Git-based workflows, such as using pull requests for lightweight peer reviews on API definition changes.
3. Enforce consistency with automated API style guide checks. Integrate automated checks directly into your CI/CD pipeline, analyzing your API definition files against your organization's style guide. These checks, including API linting and breaking change detection, act as vigilant guardians, ensuring your APIs adhere to crucial security, usability, and documentation standards. This proactive approach catches inconsistencies early, saving time and resources.
4. Conduct API conformance checks. These automated tests ensure the implementation matches the design, thereby preventing API drift. Generate implementation server stubs (and client SDKs, if necessary) from your API definitions, and implement API conformance tests as a quality gate to detect any divergence between the code and API definitions.
5. Store API gateway configuration in a declarative format in version control. API gateway configuration files contain the set of rules an API gateway follows to manage and route incoming API requests to the appropriate backend service. Examples of the configuration they contain include routing rules, rate limits, and security policies. To support the GitOps approach, the gateway configuration files should be specified in a declarative format. Unlike imperative formats, which specify a sequence of commands, a declarative configuration file outlines the system's desired state. This is crucial in the GitOps approach and fosters collaboration between development and operations teams on configuration changes.
6. Continuously reconcile the desired and actual states of your API gateway configuration. Deploy API configurations using the CI/CD pipeline and software agents to automatically apply the desired configuration state to the actual deployed system state. Avoid manual changes through the API gateway's UI; instead, make changes via pull requests and utilize the pipeline and software agents for deployment.

The automation introduced by APIOps ensures:

• APIs align with the organization's style guides
• Elimination of drift between API reference documentation and the runtime API
• Maintenance of consistency between the deployed API configuration and the desired state in version control
• Streamlined workflow through lightweight pull requests,
• A comprehensive audit trail of changes via the version control system

Kong provides a full API management platform including a suite of development tools that can help you implement these APIOps principles. Let’s look at what APIOps with Kong looks like in detail.

APIOps with Kong

How can Kong help us apply the principles of APIOps? Let’s look at each of the principles outlined above and see how Kong projects and products provide us the necessary tools to implement successful APIOps methodologies. 

1. Embrace an API-first approach to API development

Starting with API design allows the development process to flow from a natural source of truth in the API definition. For REST-based APIs, the de facto standard is OpenAPI specifications, which can drive a variety of development needs including documentation and code generation.

Kong Insomnia provides a collaborative development tool that is centered around API-first development. API specifications are at the heart of Insomnia allowing developers to build specifications using an integrated development environment that includes real-time collaboration, validation, and testing over your API specification files.  

2. Treat API definitions as code

API specifications are perfectly suited to be stored in version control systems that track historical changes and promote automated workflows on change events. Insomnia does its part by supporting Git integration out of the box allowing you to clone, synchronize, and push design documents directly to connected git repositories. Multiple hosted git platforms are supported, including GitHub and GitLab.

3. Enforce consistency with automated API style guide checks

Linting is a common practice that validates code against a set of rules by looking for potential errors, stylistic issues, or deviations from standards. Insomnia directly supports specification linting, and will flag rule violations while developing APIs in real-time. This process helps prevent potentially damaging changes from making their way into production systems.

4. Conduct API conformance checks

Validating that your service implementation conforms to your API specification is critical. Kong Gateway can assist in this principle by providing an additional layer of specification validation for requests and responses as they flow through the API gateway layer. Kong Gateway supports an OpenAPI Specification validation plugin that will validate incoming requests against the schemata located in your OpenAPI specification prior to routing them to upstream services. Service responses can also be validated against the specification prior to routing them to requesting clients. These validations can catch errors before they arrive helping protect services and clients form invalid data and helping engineers diagnose issues faster.

5. Store API gateway configuration in a declarative format in version control

Kong Gateway’s proxy behavior can be configured declaratively using the decK command line tool. The decK declarative configuration format is a simple YAML-based syntax perfectly suited for storage in version control systems.

Out of the box, decK supports the conversion of OpenAPI specifications to the decK declarative format, supporting an API-first workflow. Furthermore, decK supports various commands to enable APIOps-based pipelines within your CI/CD systems. Gateway configuration generation, transformations, and linting are all supported directly in the command line tool. These commands can be assembled together allowing you to construct very custom API specification and gateway configuration delivery pipelines.

The Kong Gateway declarative configuration assets naturally fit within version control systems and the APIOps capabilities of decK are designed to work directly in CI/CD systems supporting automated APIOps-based systems.

The decK documentation has more details on enabling these APIOps capabilities.

6. Continuously reconcile the desired and actual states of your API gateway configuration

In addition to API specification and Kong Gateway configuration management, decK provides the ability to directly manage the state of the gateway from those configuration files. This allows users to build a full lifecycle APIOps workflow that spans API specification construction all the way to delivery. Ensuring that the state of the gateway matches the intended configuration is key to building a robust API gateway layer. Let’s see how decK can help with this final principle.

Calculating a diff from the decK configuration file with the current state of the gateway is a single command.

Pairing this command with widely available CI systems allows you to build a workflow to act upon those calculated differences in code review style development processes. Below is a snippet from an example GitHub Actions workflow that will calculate a Kong Gateway runtime diff and post the result as the description in a new PR along with the configuration changes that would create the changes.

The full file listing can be found in the KongAir example application project.

This PR workflow can be paired with a subsequent command that will synchronize the changes when the PR is approved. The Kong Gateway configuration can be easily synchronized by using the sync command.

Adding this command to another GitHub action can automate the final delivery step of the API configuration.

The full listing is available in this KongAir example.

Conclusion

A solid APIOps process will be key to your organization's success around API delivery. Following the principles outlined in the Automating API Delivery book sets a strong foundation for your engineering success.

Kong provides the necessary tools to technically achieve these results with Kong Konnect and APIOps. Follow the Getting Started Guide for Kong Konnect and be up and running with your first API in under 10 minutes. To learn more about APIOps, check out the on-demand webinar Harnessing AI for Rapid API Delivery.