Nauman Ali is the Product Manager at Stoplight. This article by Nauman discusses API governance and how to automate some pieces of it.
API governance is a term thrown around a lot. There’s a lot that encompasses API governance. But we’re primarily talking about the pieces you can automate and make this process scalable and work better.
From the API report last year, standardization of APIs was the biggest challenge faced by companies. As the globalization of companies is on the rise, developers are spread across the globe. It is harder to ensure that everybody follows your standards and conventions. Companies have started API governance programs to ensure consistency in the creation and consumption of APIs. Companies could have central teams reviewing every API change being made. But this is hard to scale. The central reviewing team becomes a bottleneck. Developers may find ways to bypass reviews, which leads to failed standardization. This is where automation helps.
You can build a well-documented set of automated standards that help the governance team. It will also help the designers and developers know what is expected of them. The governance team need not focus on basics and is no longer a bottleneck.
Automation of API governance
An API style guide is a set of standards that all developers and designers should follow, like naming conventions and security conventions. It should not be a pdf guide but an automated style guide. It should have a set of rules that can automatically run against your API designs and point out the issues. Your guide should have best practices on using API specifications.
OpenAPI / AsyncAPI Best Practices
- Don’t use OpenAPI2.0
- Add tags to each endpoint, and tags should be defined globally
- Always have an OpenAPI / AsyncAPI version
- Operation IS should always be defined and unique
- Add contact/license information to API documents
You can make that a rule so developers know the classification format and version they must use. These can be codified into your style guide. As developers and designers look to create these documents, they can easily get feedback on what they should potentially do to improve the quality of their API specifications.
API URL Guidelines
Host
- Must be lowercase
- Must not be a trailing slash
- Host must follow a structure
Paths
- Must be kebab-case
- Don’t use file extensions in paths
- Don’t add HTTM methods to paths
- Avoid special characters
- Use nouns for resource names
Parameters
- Don’t include query params as part of the URL
- Query and path parameter casing
Versioning Strategy
There are multiple strategies that you can follow in versioning. Some people might want to use path-based versioning, while others want to do it in the URL, headers, or query.
Security Best Practices
HTTPs
- Must use HTTPs
Secure your API with a security scheme
- Must use Oauth2, OpenID, etc
- Define security globally or at an operation level
- Always have a 401 defined
Don’t use unsafe schemes
- Use known security schemes
- Don’t use HTTP basic / bearer token
- API key in header, cookie, or query is not a great idea
Open Ended parameters can be exploited
- Limit array size and numbers
- String should have a limit and pattern
- Disable additional properties o constraint them using min/max properties
OAuth2 Best Practices
- Must use https on oauth endpoints
- Avoid using implicit and password grants
- Always have scopes defined
Rate Limiting
- Always include rate-limiting headers
Error handling
- Error response must follow a particular structure
- Always include popular error responses
- Enforce error object type
- Must use problem JSON
- Create rules for errors, not just a 200 response
API documentation guide
Set basic rules like length, grammar, and spell-check. So, you can create a basic set of rules that can improve your API documentation. You can have a tool to generate documentation automatically.
Tooling Setup
If you design APIs, you probably use some sort of tooling downstream. That would require you to add some x extensions. You can add specific limitations on adding these extensions. This will help developers identify what is supported by the API and what is not. The same goes for cogeneration.
Industry Standards
If you are in a particular industry, which has standards like open banking, or IATA in the airline industry, you could codify those.
Rolling out API style guides
These are some things you can add to your style guide. Rolling out the style guide is important. Steps that you can follow are –
Socialize the style guide within your organization. Everybody might think differently. Have a good collaborative conversation on it to ensure that everybody agrees on the basic set of rules.
Start small. You don’t need to add all rules at the start. Start small and iterate over it over time.
Bring it where your designers or developers are. You don’t want developers to have to read 100 pages of documentation. Add rules to the design and development environment.
Make it part of your review process. Providing a style guide gets you 80% there. Enforce these rules as part of your CI in the review process to ensure guidelines are followed. The review process can now focus on business capabilities, use cases developer experience, making sure that it doesn’t require five calls to do a basic use case. This decreases the time that reviews take. You can get faster to market and hopefully make much more consistent APIs.
What else can you do?
Now style guide is just one piece of it.
Reusable set of API components
You can do other things to augment your governance process, like creating a reusable set of API components, like models, parameters, head headers, error responses, and things people can use. This brings consistency because you have a set of things that people can get started with.
Templates – You can provide templates with best practices and commonly used patterns to kick-start the design process itself.
Conclusion
An automated set of API standards helps the governance team in the following ways –
- Fast reviews
- Great visibility
- Better scalability
As you automate and provide more of these tools, your designers and developers hopefully build much more consistent APIs.
