API Governance Best Practices

API Governance is a term thats been floating around more and more over the last decade, but what does it mean, what is the point, when do you need it, and what are the best practices?

What is API Governance

Organization with multiple API teams will have noticed that each one of their APIs start developing differences, different data formats, different error formats, multiple authentication systems, etc. These differences can start to pile up problems.

The more your APIs differ from each other, the harder it can be for API consumers, either internal to the organization, or external customers and other partners. The more differences there are the less people can reuse code between the APIs, with each integration becoming a custom effort.

Using multiple authentication strategies can not only become complex to handle, but it can also see security issues pop up when some outdated systems are used.

Leaving all of the decision making to each API team can become problematic, especially when they are overloaded with feature requests and desperately trying to do their job, but sometimes it's also down to experience. Not every single backend developer is an experienced API developer, yet that is often what is expected of them.

An API Governance team, or an API Center of Excellence team, can act like internal API consultants, helping establish quality and consistency throughout the API ecosystem of an organization, helping with everything from planning, ongoing API design reviews, setting up monitoring to keep an eye on performance issues, and testing to ensure the APIs are working as intended.

All of this work can ease integration for customers, meaning more income for the business. It can help simplify decision making for API teams, leading to quicker delivery instead of wasting time reinventing wheels every time. It can also reduce the number of support tickets coming in from confused customers, helping reduce overheads of running the business.

To learn more about the benefits of API Governance, check out this article on 5 Ways API Governance Can Enhance Your Security Foundation.

How does API Governance fit in with the API Lifecycle

The API lifecycle is the concept of an API being planned, born, evolving over time based on usage and feedback, to its eventual deprecation and sunset, possibly being replaced with a new API that is starting its own lifecycle. This best writeup I've seen on the topic is Full API lifecycle management: A primer.

_Diagram by Nicolas Massé, 2019, Solutions Architect at Redhat.

Every phase will be handled differently in different organizations; some will be skipped, and that may be fine or it may be a problem, and over time different people will be being involved for different overlapping bits. All of these phases have their own workflows and different tooling to help power it all.

Which Tools Help with Which Lifecycle Phase?

Some tooling vendors naively believe their products can help at every single stage of the API lifecycle, but this is never true.

Stoplight's CTO Jason Harmon wrote Full Lifecycle Vs. Specialized: What Companies Should Consider When Creating APIs wrote a piece explaining that APIs are too variable to be defined by a single workflow, and tooling companies should not try to do this.

Attempts to organize everything API into one bucket may be leading people in the wrong direction. Companies building API programs may benefit from surveying the ecosystem and engaging the original innovators and disruptors who have addressed their particular needs.

API tooling companies, on the other hand, are able to better enable customers to adopt whatever combinations of products best serve their unique API lifecycle by making sure that products are best-in-class and as interoperable as possible.

The key to handling every stage of the API lifecycle is not to find one mega-expensive behemoth of software that can do everything in some very rigid way, but to have integration points between multiple tools that can all specialize in their own areas but speak the same language.

OpenAPI is one of the key integration points, acting as an API contract thats readable by both machines and humans and can be used to generate mocks and documents, scan for security issues, fuzz testing, and let load testers know where to spam. It can act as the contract for all these tools, all of which can be created and managed by different people, from OSS to SaaS.

Whether your OpenAPI documents live in your Git repository or hosted on an accessible URL, defining your contract in OpenAPI early and evolving it as you go will keep all of these different tools and teams talking the same language and avoid creating multiple sources of truth that all then end up disagreeing and confusing everyone.

Let's have a quick look at some of the tools you might want to look at for different stages of the API lifecycle.

Strategy Tooling

This stage is more about planning, research, business requirements, and questioning stakeholders, so that can involve whatever communication and collaboration software you like.

Zoom (https://zoom.com/)

Talk to users and stakeholders for this API as you can, and find out what problems they need solving.

Google Docs (https://docs.google.com/)

Start writing up requirements, and think about your API model, not database models.

Miro (https://miro.com/)

Using diagram software like Miro or Lucid Chart helps teams with online collaboration. White-boarding, journey mapping, and sequence flow diagrams can all help make sure you've fully understood the problems you're trying to solve before anyone starts talking about which HTTP endpoints and methods are going to be used.

Design Tooling

The design space can just mean cracking open a text editor and starting to list out endpoints and payloads. More recently, this came to specifically mean creating the OpenAPI documents, which is just a standard syntax for describing endpoints, payloads, headers, and everything else you'd expect to find in an HTTP request/response. Sadly, the most powerful OpenAPI GUI's have gone SaaS-only, leaving most API teams stuck editing large YAML files by hand, but OpenAPI is designed to be human and machine-readable anyway.

Stoplight Studio (https://stoplight.io/)

The desktop version has been sunset, but if you have the money, you can sign up for Stoplight Platform and use a powerful visual editor to manage OpenAPI that lives in your Git repositories.

Redocly VS Code Extension (https://marketplace.visualstudio.com/)

It's YAML, but it's local. They help you write more OpenAPI, and you can preview real-time, which helps you learn.

The API Design phase is poorly served right now, but there are a few techniques you can use, like using GitHub Copilot to write OpenAPI for you. People worry it won't be accurate, but using the next stage you can make sure your OpenAPI is not only valid but useful and high quality.

Linting Tooling

Once you've got a rough draft of the API you'd like to build, with all the endpoints and payloads described in OpenAPI, it's a good time to start using automated checks to make sure that both the OpenAPI and the API it is describing follow particular standards in your organization. If you don't have any standards, now would be a good time to start thinking about them.

When you know what standards OpenAPI linting tools Redocly or Spectral can help with all of this. API designers can run API linters via the CLI, continuous integration, or baked into their IDE/editor, and can cover several different categories of automated checks.

1. Syntax Validation: Is this valid JSON or YAML, and is that JSON or YAML representing valid OpenAPI syntax.
2. Semantic Validation: The syntax might be valid, but variable names might be wrong or required things might be missing, which is basically a more advanced type of "is the OpenAPI valid" check.
3. Data Validation: The examples in the request/response bodies need to be valid against the schemas defined.
4. Standards: Does the OpenAPI or the API it is describing follow particular standards. This could be requiring the use of a data format like JSON:API then using the JSON:API to make sure the API conforms to it. You could also use the OWASP Security to push people away from HTTP basic towards modern approaches, ensure JWTs are using RFC8725, and use the rate-limiting draft RFC instead of making up custom approaches.
5. Style Guides: Picking and choosing all of the standards and conventions to use for any given API could lead to different standards being picked across multiple APIs, but a style guide can solve this. Not just the "Somebody wrote a manifesto that nobody ever looks at" API style guides of old, but an automated style guide that can give feedback early and often in the process to guide the API to being consistent from day one. APIs You Won't Hate have a sample API Style Guide you can use as the basis for your own.

All of these rules can be linted everywhere, desktop to CI, early and often. It's easier, cheaper, and less emotional to change an API early in its conception than much later when code has been written, prototypes have been deployed, and clients have started integrating with it.

Mock Tooling

An API design eventually progresses to a point you can no longer hypothesize whether this is going to be useful for the clients or not. Instead of guessing, you can spin up a mock server, like Wiremock or Wiretap.

Wiremock example dashboard

These mock servers take your OpenAPI document as input and generate an interactive HTTP server that attempts to emulate your API based on the information provided in the document. These can run locally, on your servers, or on their servers, but the point is that somewhere a mock server runs somewhere.

You can then hold feedbacks sessions (or use GitHub issues on the repo that contains the OpenAPI) to facilitate conversations between the API team and the API consumers and stakeholders to make sure the API is doing what they expect, in a way thats useful. You're looking out for both over-fetching (too much information coming back at once) and under-fetching (forcing consumers to call a silly number of endpoints to solve their workflows) to create an API that's just right.

Testing & Implementation Tooling

There's a little bit of disagreement about the order of these phases, with the diagram above showing test comes before develop, but ultimately the order doesn't matter. Whether you're doing Test-Driven Development in a codebase, writing the test specs that need to then be fulfilled by the code, or writing a bunch of code and then adding some contract tests later, it doesn't make much of a real difference.

It's the sort of thing you can let a team decide on, and giving them this sort of freedom helps avoid pushback because if there's no benefit, why enforce it.

Either way, you can write down the requirements, then make sure the implementation meets those requirements before it's signed off by the governance team during a "design review".

There are a lot of different types of testing (https://blog.stoplight.io/introduction-to-api-testing), but OpenAPI-powered contract testing is a huge win. You can make sure the OpenAPI you used to create mocks earlier is being conformed to in your API implementation by reusing that same contract for the contract testing. That means the mock and the implementation have to match, unless you decide to make changes and that will be easily noticeable in the OpenAPI, and it will update the mocks so the API consumers your working with in the mock phase will know about it.

OpenAPI-based Contract Testing

PHP: Spectator
NodeJS: jest-openapi

• Ruby: openapi_contracts

Why write a bunch of assertions saying "this should be a string, this should be an email address" again when you can just let OpenAPI-powered assertions do that.

// Import this plugin
import jestOpenAPI from 'jest-openapi';

// Load an OpenAPI file (YAML or JSON) into this plugin
jestOpenAPI('path/to/openapi.yml');

// Write your test
describe('GET /example/endpoint', () => {
  it('should satisfy OpenAPI spec', async () => {
    // Get an HTTP response from your server (e.g. using axios)
    const res = await axios.get('http://localhost:3000/example/endpoint');

    expect(res.status).toEqual(200);

    // Assert that the HTTP response satisfies the OpenAPI specification.
    expect(res).toSatisfyApiSpec();
  });
});

Whether first or last, the goal here is to make sure this test passes by making sure the code returns a payload that aligns with the description of the payload, tweaking either or both until you get to a passing test.

Server Code Generation

Some people prefer to reduce the effort of writing code that matches the OpenAPI description by using code generators to generate their backend code based on the OpenAPI document.

You can literally create entire "server stubs" that essentially handle all of the CRUD (Create, Read, Update, Delete), then sprinkle a little business logic into the right places to power anything more complicated than the basic CRUD.

Governance can help by creating standardized "templates" for these code generators, reducing the barrier to entry for multiple API teams who, left to their own devices, may be happier writing all this code from scratch. Creating a lovely template can make this so simple that teams are happier as it produces a good result without them having to do anything much, but this does get exponentially more difficult the more languages different teams may be using.

Request Validation with OpenAPI

A handy middle-ground between "server generation" and "writing all the code yourself and trying to get it to match" is using OpenAPI-powered request validation to handle a whole lot of the usual logic on the fly.

To use a very simple example, if a widgets schema requires a name property, an OpenAPI-aware HTTP middleware registered with your web framework would reject a request coming in that was missing that name property.

$ curl -X POST http://localhost:8000/api/widgets \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Replicator"}'

{
  "title": "Bad Request Body",
  "status": 400,
  "errors": [
    {
      "message": "object at root is missing required properties: name",
      "code": "required"
    }
  ]
}

This cuts down the amount of repetition involved with writing code, but as it's done on the fly, you don't have to worry about generating new code and overriding old code just because the OpenAPI changed.

Security Tooling

Once you've got the API working as expected, there is often a bit of a rush to production as the team is feeling the heat from business that want this new API live right now.

A solid API Governance program would insist on a bit of time spent on security before that happens, as the earlier this feedback can be provided, the cheaper and easier it is to make it happen.

Spectral can be used to check for the most common problems using the [spectral-owasp] ruleset based around the OWASP API Security research, which is handy if you're already using Spectral.

Treblle will also provide a lot of similar feedback (using outdated authentication strategies, missing rate limiting, forgetting about important security headers, not using HTTPS, etc) through its API monitoring and analytics functionality.

Trebble API security audit

People often forget to get something like Treblle involved before going live, leaving it until the first production problems are experienced, but once again, getting this sort of feedback earlier on can help you spot important issues before clients or hackers do, making it far easier and cheaper to implement changes.

Manage Tooling

API management commonly falls under the responsibility of the DevOps, Infrastructure, or Platform Engineering realm, but the API Governance folks can get involved here to ensure that the infrastructure is set up ready for a good, consistent experience.

Come up with Service Level Agreements, covering up-time (99%, 99.9%, 99.99%) and decide which APIs need which level of support. Decide what sort of response times are acceptable and set up alarms for APIs that fall outside of that, so the API governance team can help the API teams optimize to get back within the SLA. Monitoring tools can help, and we'll talk about those later, but getting this all agreed upon now and making sure the infrastructure is there to track, report, and improve on this will save a lot of flailing later.

This can include API Gateway tools like Kong, AWS Gateway, Zuplo, or for microservice architectures, this might require a Service Mesh to help lock down which APIs are talking to each other and the timeout durations that are acceptable. Either way, this is less of a space for API Governance, but they should be in the room.

Distribute Tooling

Getting this API out there in the real world to be consumed can be a daunting task, but it comes down to a few things.

1. Who is your audience?
2. What do they need to know?
3. How are you getting this information to them?
4. Who is managing the platform for doing this?

If it's general public or a few key stakeholders, this will vary wildly, but somebody needs to be thinking about this and acting accordingly, which is another place governance can get involved. They will often be responsible for setting up a "documentation portal", which can contain all of the API reference documentation along with a bunch of other guides, providing the right level of authentication to make sure only the right people can see it, and handling API keys so we know who is working with the API.

Zuplo is brilliant API Gateway that runs your OpenAPI description, which can be powered by Git and evolve with your API. This pushes a lot of the work to the developer teams, but means that API Design reviews can also check for API gateway changes all at the same time. Zuplo also produces OpenAPI-based documentation, which can let users sign up for API keys right from the documentation, saving you a whole lot of faff coding those application interfaces yourself.

SDK Generators like Fern, Stainless, Speakeasy, and OpenAPI Generator can also help here by giving API consumers code to work with instead of forcing them to figure out the API documentation and write all of the integration code themselves.

Develop & Consume Tooling

Once you've got OpenAPI-powered documentation and SDK's out there, you can sit back and let the API consumers do their bit. With all of the up front design, this should be going smoothly, as you had a chance to iron out the majority of bumps in the road, but they will be in touch with concerns and support helpdesk will become a source of feedback, which API product managers can discuss with API governance teams to see what actions (if any) should be taken.

Often the answer will be:

1. Improve the documentation
2. Add backwards compatible improvements to the API
3. Changes to code and infrastructure to improve performance
4. Storage and categorize feedback to be considered in upcoming backwards incompatible versions of the API.

Monitor Tooling

As well as just waiting for feedback, API governance should help API teams get out ahead of it, using API monitoring to keep an eye on the health and effectiveness of the API.

Treblle's API Observability offering can provide real-time feedback, highlighting slow endpoints and catching API errors so you can see if consumers are having a rough time.

If will even capture payloads (sanitized, of course) to provide insight into how clients are using the API, which can suggest improvements to documentation, or perhaps suggest it's time to have a chat with the customer to see if they would like any help.

Monetize Tooling

Taking the monitoring concept a step further, you can use the insights into the usage of your API to figure out potential monetization options.

If you've got some popular endpoints that start out free and you notice a small number of consumers are creating a disproportionate amount of the traffic, this might be a good time to reevaluate your rate-limiting settings and provide extra-paid plans for power users. This helps keep the API fair for everyone and makes sure your business is getting enough profit to justify the extra infrastructure and maintenance costs of the popular service you've created.

You can achieve this through Treblle's API Observability, which provides detailed insights and helps you optimize API usage and performance for better monetization.

The API Lifecycle Never Ends

The API lifecycle's last step loops back the start because it's two constant feedback loops. For this reason there is never a best time to start API governance because most tech companies will already have some APIs that cannot be changed on a whim, and none of them last forever, meaning there is not really any rush to even try doing that.

For example, the design phase is not one thing that happens during the planning stages; it's something you should consider every time any changes are made at all. A new version if you use API versioning, a new endpoint or property if you use API evolution, both would go through their own design phase, which can be as simple as updating the OpenAPI in a pull request and getting the Governance team to comment on it, also known as API Design Reviews.

Getting a program together, picking standards, naming conventions, thinking about service-level agreements, improving the reuse of API models, making API documentation easier, reducing "time to first request" with better SDKs and code samples—all of this can be done at any point, but the sooner you get it set up, the better the outcomes will be.

Starting API Governance

Creating a good governance program for a business will often be very unique to the business, the structure of the teams and management, and more importantly, the level of interest and commitment from both.

Getting everyone on board can be incredibly difficult because management need to want this, and it cannot be done without it. API teams trying to do this without support from the CTO or engineering directors will be fighting a constant battle to do "extra work", trying to sneak it through amongst all their other work, and this can have negative impacts on not just deliverables but also careers.

Conversely, if the higher-ups want this to happen, they need to explain the benefits well enough so that it doesn't seem like pointless busywork being dumped onto everyone who already has enough to be getting on with. It needs to be explained as a time-saving exercise in improving workflows, and a certain amount of proof of concept needs to be done before getting everyone on board so they can see benefits first.

Most Important Points

API Governance is here to add value, not provide unnecessary roadblocks to getting critical work done. There's no point having the most amazing, consistent, performant APIs if the business has gone bankrupt due to losing business to a faster-moving competitor. These things are a tricky balance.

Defining standards and reusing them should be advertised as a way to reduce time spent reinventing wheels, enabling more code sharing between APIs, and letting teams focus on delivering functionality instead of working out how to add pagination or coming up with some unique API token strategy. These standards can be delivered through linting at any phase, automated testing, API design reviews, and baked into the code throughout implementation phase.

A lot of this comes down to OpenAPI, so learning how to create the perfect API description is going to help massively.