Most organizations maintain dozens or even hundreds of APIs. Maintaining consistency and avoiding redundancy quickly becomes a major issue. API governance helps organizations declare and adhere to guidelines for new and existing APIs. There are different approaches to encourage conformity in API design, including governance review and automated restrictions.
In this post, we’ll explore both of these patterns, as well as a lighter weight hybrid model.
Governance Review Requires Human Oversight
A traditional approach is governance review. This method centralizes interface design decisions with an architect or team of reviewers. The implementation is performed by individual teams, but goes through a review process. Typically the review teams will establish parameters to follow, but have the opportunity to be flexible. This approach may produce better outcomes (depending on your API goals), but can take more time.
A governance team often looks for consistency within an API, as well as compared to the other APIs your organization produces. This could include high level choices like protocols and data formats, but also might be more detailed, such as the naming of endpoints and fields. If the APIs do not follow established criteria, there is typically a revision cycle where the team can fix or justify the issues.
As one can imagine, this method has the potential of severe bottlenecks. It relies too heavily on human resources, which are often limited in the centralized review team. Each API may receive multiple rounds of revisions, further extending the backlog. While humans are good at nuance, they can miss more detailed issues. Or, they may simply decide not to fully enforce some conventions due to time constraints, especially if an API is largely compliant.
Automated API Governance Can Be Too Rigid
One way to implement more streamlined API governance is to use tight restrictions to ensure conformity. This approach can bypass the need for a centralized team to review APIs. Instead, scripts and templates will catch issues programmatically. This machine-driven approach is scalable, but has the downside of necessarily removing nuance.
A governance team is not eliminated, even when the review is automated. Organizations require architects and other experts to identify the criteria and codify how you determine if an API conforms. API description formats, such as OpenAPI, play an important role to define exactly how an API works: what are the endpoints, data requirements, and status codes, for example. Many consistency elements can be implied or directly confirmed from the presence of certain fields, for example.
Automated validation can significantly speed up the review cycle. Implementation teams get immediate feedback on their APIs, perhaps even before commiting code. On the other hand, the rigidity requires teams to build against a spec that might not have considered their unique needs.
Hybrid Governance as a Middle Ground
As in many situations, a mix of approaches can provide the best solution. You can take the best of both governance approaches to find the right balance for your organization.
Consider these strengths:
– Humans can handle grey areas where machines cannot
– Machines will catch details that might escape the human eye
A hybrid approach might use strict requirements to ensure status code coverage, but leave endpoint naming for human review. Further, you can create guidelines and checklists that encourage good API decisions without creating a gauntlet everyone must pass. You can always adjust both machine-readable and human review parameters as you learn the right balance.
The approach fosters creativity, which is known to precede innovation. It also encourages collaboration across teams, rather than a hierarchy of approval. Even better, you can work faster and improve your API program.