November 9, 2023

Time for GitOps to come to APIs

GitOps is eating infrastructure.

APIs are right next door, nibbling away at your monolithic software.

When you use GitOps, you define the desired state of your production environment through code (IaC), often in YAML/JSON files.

APIs have a similar method of expressing how they should be deployed and operate: OpenAPI definitions… which are also expressed in YAML or JSON.

Both of these definitions are written as code. Both are declarative. Both can be version-controlled and edited using anything from vi to VSCode or specific GUI editors. Both use standardized syntax and structures. Both are designed to help people and machines understand how a service should function without needing to learn every nuance.

If you could imagine bringing these expressions together, you could keep everything you love about building simple and consumable APIs, but also loop in everything that’s making GitOps the new must-have for DevOps practitioner teams everywhere. These YAML and JSON files are not interoperable, but you can nudge their designs and intentions onto parallel tracks—if you have the right pieces in place.

What you need to GitOps-ify your APIs#

1. A thoughtful API design#

By thoughtful, I mean that before you begin writing code or thinking about a deployment strategy, you ask plenty of questions about the technical and business requirements needed to get buy-in from customers, your developer peers, the DevOps folks who will be in part responsible for keeping your API available, and beyond.

You might take a design-first approach, but that’s not required to build a solid API. At a minimum, you should be thinking about the 3 pillars of an API program:

Authentication: How will the partner authenticate securely with your API?
Documentation: How will the developer learn how to use your API?
Protection: How do you stop a rogue for-loop in a partner’s code from taking down your whole business?

While those pillars are a good starting point, you should also consider how you’ll handle versioning, analytics, routing, caching, abstraction/customization, and code quality standards, all of which play a role in how you configure your developer environments, Git repos, and CI/CD pipelines.

2. A (valid and complete) OpenAPI definition#

This YAML or JSON file is the single source of truth for how your API should operate. It’s an in-code definition of how you plan to answer all the questions you’ve asked in the design phase, down to the paths your API responds to, how the backend logic should structure its responses, and so on.

If you spent the time to properly design your API by being cognizant of business requirements and technical challenges, you’ll want to feel confident your OpenAPI definition is as valid and complete as possible. Drop a file or URL to a publicly-hosted definition on RateMyOpenAPI to see how you score against current best practices and follow advice on fixing invalid schema examples, missing descriptions, a lack of rate limiting, and more.

Remember that the more valid and complete your definition is, the better you and other developers will parse it to build the business logic and supporting infrastructure (as code) to support transforming, storing, and returning data.

3. A Git-friendly API gateway#

In a merge of GitOps and APIs, your Git provider—whether that’s GitHub, Gitlab, Bitbucket, or any other—becomes your checkpoint for deploying your API gateway through additional definitions, which are also stored as code and source controlled like everything else. Change management and quality control happen in pull requests, protected branches, and code reviews, where only merged API gateway logic is ready to go live.

Even better, a Git-friendly API gateway lets you develop in two directions:

First, you can edit your OpenAPI definition directly (or, when using Zuplo, you can edit your routes.oas.json file), which your gateway should automatically parse, to change authentication patterns or response types from new or existing routes.
And second, you can edit your API gateway’s configuration to extend your OpenAPI definition with additional features or middleware execution, like archiving requests to storage or passing consumer data to your API.

4. A deployed API gateway (on the edge)#

Managing an API gateway on your existing infrastructure is certainly possible, but doing so dramatically increases the challenge of employing GitOps through your entire API lifecycle. Given the complexity, eventually different teams will be taking ownership of parts of the deployed API, creating more silos.

Will DevOps buy in? Will those folks like you (re)configure your API gateway, or will they put too many manual checkpoints in your way? Do they get GitOps workflows? Is your infrastructure composable into developer environments? Can your current tooling support the authentication scheme of your dreams?

Abstracting your API gateway to edge infrastructure gives you an immediate operational advantage. Instead of spending cycles worrying about configuring the infrastructure to enable API key management or multi-cloud support, you’ll have more time to optimize existing routes and build new ones as your business case changes. Your consumers, whether human or machine, will be happy with the low latency of an edge deployment, too.

5. A developer portal#

Documentation is fundamental to any API program. It’s the leading edge where any developer first learns how to call your API and then extend their understanding until they’re an expert, which means it needs to be comprehensive and accurate to the latest version of your APIs.

API documentation generators like Swagger have been around for a while, but what’s even better than amazing documentation? A genuine developer portal, where the reference for each route and the relevant code samples are enriched and scoped by your user’s account, including pre-generated API keys for handling authentication.

You could try to build a Stripe as Twilio-esque developer portal yourself, likely requiring thousands of hours of engineering time and a team of dedicated technical writers, or you could automatically generate 80% of the functionality directly from your OpenAPI definition and API gateway configuration with a gateway like Zuplo. Your pick.

What’s next: Zuplo as the bridge between GitOps and APIs#

The great thing about bridging GitOps and APIs with the above tooling is that it’s a relatively modular technology stack—you don’t need to rip out your existing APIs or change your development processes to give it a try.

Instead, the YAML and/or JSON definitions you already have, which you once believed served a single purpose, suddenly become sources of truth that extend into solutions that would have otherwise required yet another SaaS or third-party dependency. You can ‘git’ quite a lot from GitOps on your APIs:

A simplified architecture, using a CD pipeline, to pull desired state from Git and maintain the deployed resources with a reconciliation loop.
Shift-left your API security, testing, and policy management efforts without overburdening developers.
Control complex routing and ingress features, like rate limiting and authentication, as easily as you do code.
Solid discoverability based on having a single gitops repository for expressing desired state and delivery in a tree of folders and files.
Better security when your CD platform will use a read-only pull operation to get configurations and deployments from Git and manage desired state.
An audit log in the form of pull requests, code reviews, and Git commits.
Simple rollbacks by running git revert YOUR-LAST-WORKING-COMMIT and pushing to main.
More production-like developer environments, whether running locally on your workstation or in the cloud, that let you extend your existing API as simply as creating a new branch in Git to track your changes and deploy them with the same CI/CD pipeline you use for production.