We always recommend that organizations strive for consistency across all their APIs to achieve success. One way to do that is by using an API Design-First approach. However, to truly ensure consistency across all your APIs, you need governance.
A successful API governance strategy involves:
- Providing guidelines ahead of time.
- Reviewing APIs early in the design process.
- Automating as much of the governance process as possible.
API governance reduces costs and improves API quality. Its benefits come from aligning contributors, establishing efficient processes, and promoting consistency.
This article explores API governance, API components, and the things you need for an effective API governance program.
What is API Governance?
API governance is the practice of applying rules and policies to your APIs. You create processes that standardize various aspects of your APIs. The major activities that API governance includes are:
- Descriptions
- Contracts
- Designs
- Protocols
- Quality Reviews
This standardization helps ensure that all your APIs remain consistent even when different developers design and build them. An effective API governance program helps organizations ensure that every API is high-quality and discoverable—whether they create a few APIs or a few thousand.
Why Implement API Governance?
Achieving consistency across your APIs means that you can reuse existing components. And part of governance is tracking APIs and making them discoverable so that developers can easily find existing API artifacts and reuse them in future designs. This means that developers only have to build components once and won’t end up duplicating code.
When you enforce standards, you prevent developers from having to reinvent the wheel. They can spend more of their time on tasks that benefit the business, like building new services. API governance also helps keep everyone involved in your API program on the same page. When stakeholders have misunderstandings about API goals or designs, it can cause API programs to fail.
Before You Begin an API Governance Program
Before you begin implementing your API governance program, you need to do some planning. We suggest your planning process include the following:
Identify Your Goals and Stakeholders
You need to figure out where you want your API program to go before applying governance. Create an organizational chart that identifies all the stakeholders across the business. Identify who works on creating APIs and track their workflow. Interviewing company leaders and stakeholders will help you map out the objectives and issues of your API program. Your API roadmap should address all the types of APIs you intend on creating—internal, partner, or public. It should also include key objectives, such as digital transformation or APIs as products to generate more revenue.
Create an Inventory of Your APIs
You might be surprised at how many companies build APIs but then lose track of where they are. Before you can implement API governance, you need to take an inventory of all your APIs, both existing and in development. Create a list of the APIs each developer or team creates or maintains. When you don’t know where all your APIs are, you often end up with duplicate, inconsistent, or even broken APIs. Some companies may have an API directory in place but don’t maintain it well. So, it ends up out of date or missing some APIs.
Explore Your API Landscape
You can use Stoplight to inventory your APIs and determine the status of your API landscape. Once you’ve added your API projects to Stoplight’s Explorer, you can discover things like:
- Your existing APIs.
- API descriptions and formats used.
- Documentation for each API.
- Security policies in use. (good API security governance is a must, here’s a security style guide you can use to help with that)
- Changelogs for different versions of your APIs and schemas.
We recommend using Explorer to share this information with stakeholders. It is a central repository for all the design assets across your organization and serves as a single source of truth.
Decide Which Terms and Meanings to Use
Among the things you’ll want to standardize are which terms and meanings to use in API designs. Some words have multiple meanings. For example, a “travel itinerary” and a “car rental itinerary” are different things even though they share the same term. So, an API with “itinerary” as an endpoint will return different responses depending on the context. Make sure everyone is on the same page regarding design elements like naming conventions, syntax, and letter cases. For more on this, check out our takeaways from the API Intersection episode with Michael Hibay.
Design Reviews in API Governance
Design reviews are an important part of API governance. You need to have some checks in place to ensure API consistency. When looking at what companies use, there are three basic patterns that define types of reviews:
Manual Design Review
The traditional approach to design reviews involves a centralized team of reviewers who validate API design decisions. They look for inconsistencies in API designs, ensuring that all APIs follow the standards set in place. If the team finds a problem with an API, it usually goes through a revision process to fix it or justify it.
Manual design review is time-consuming because it relies on humans to complete the reviews, and some APIs will go through several rounds of revisions. It can also lead to inconsistent APIs because humans are fallible; they can make mistakes and overlook conventions.
Automated Design Review
Another approach to design review is to create strict rules to enforce conformity across all APIs. These rules can typically be automated for a faster review process. This type of review still requires humans to set the standards, review them periodically, and create the rulesets that determine when an API conforms. These automated reviews leave no room for nuance—either the API conforms to the criteria, or it doesn’t.
Hybrid Design Review
In many cases, a hybrid approach to design review works best—you use some automation and some human intervention. Automation can speed up the review process without sacrificing accuracy. And humans can see nuances in API design whereas a machine can’t (at least not yet). You create guidelines and checklists regarding API design decisions and then decide which components go through automated review and which through human reviewers. This approach allows you to speed up reviews while still encouraging collaboration across teams.
Things to Include in Your API Governance Program
Now that you’ve selected a governance pattern to follow, here are some things you should include in your API governance program:
- API Descriptions – An API description tells developers what an API does. These descriptions can be written in machine-readable data formats like OpenAPI. In addition, it’s helpful to generate human-readable reference documentation based on the API description. If your organization follows an API-First or API Design-First approach to building APIs, then you can easily incorporate API descriptions into your governance.
- Comprehensive Style Guide – Governance is about creating consistency, and one of the best ways to ensure consistency across your APIs is to create a complete style guide. Your style guide should eventually cover nearly every aspect of an API. Start your style guide out small and build it out over time. You should include things like architectural style, API description format, naming conventions, and error handling in your style guide. We plan on launching shared style guides soon (check back in a few months) to help make creating, sharing, and automating style guides easier.
- Central API Catalog – The more extensive your API portfolio becomes, the harder it gets to discover your existing APIs. You need to create a central API catalog that contains all your API design assets and dependencies. With a catalog in place, developers can search for and find APIs currently in use. You can include in the catalog collections of assets, such as API descriptions and JSON schemas. You can’t use what you can’t find, so making your APIs discoverable is crucial to effective governance.
- Reusable API Components – In addition to a catalog of existing APIs, governance programs can make individual components of APIs intentionally browsable. To encourage consistency in API designs, you can include headers, query parameters, models, and even pieces of models in a library. There are a number of ways these can be stored (including Stoplight’s Design Libraries-COMING SOON), most important is that they are discoverable. You want new APIs to be able to build on the team’s previous work.
- SLAs – Many teams building internal APIs may not think of service-level agreements as necessary. However, your governance program should distinguish the APIs that are mission-critical from those that can have downtime. How you maintain and improve your APIs could be determined by how available it needs to be. Consider classifying a tier of service for each API and make it clear who is responsible for maintaining that level of service.
- Automation – Many of the things you need for effective API governance can be automated to some degree. For example, you can use a linter like Spectral to automatically enforce API design rules (for more on Spectral, check out this blog). You can create mock APIs, generating example responses using API description files. Mock APIs allow you to test your API designs before writing any code. You can also generate documentation for your APIs automatically and ensure that documentation always remains up to date. Automation allows you to speed up governance and improve accuracy throughout the process.
Govern APIs at Scale with Stoplight
As we’ve seen, you need to do a lot of things to implement and maintain an API governance program. Stoplight enables you to collaborate efficiently on API design projects and govern APIs at scale. You can create a central repository that keeps everything in sync—API designs, documentation, style guides, and schemas—ensuring consistency across all your APIs.
With Stoplight, you always know the current state of your API designs and documentation, allowing you to apply governance effectively. You’re on your way to a better API program already!
