Lengthy review processes shouldn't be sitting in the way of innovation. Instead, most developers want a quick feedback loop without manual intervention. Yet, at the same time, amid API sprawl, organizations need standards in place to ensure consistency, compliance, and security. Not to mention that APIs meet internal design guidelines.
Thankfully, there are some practical ways to introduce API governance that enhance developer experience, instead of reducing it. The secret is that much IT governance can be automated if it's correctly incorporated into the developer's workflow. Let's review some ways to make API governance less painless for everybody involved.
Coalesce Around OpenAPI
OpenAPI Specification (formerly Swagger) has become the de facto industry standard for defining RESTful APIs. By putting a machine-readable API specification like OpenAPI at the root of your API-first development workflows, you can reap several benefits for technical governance.
For example, aligning on OpenAPI enables you to quickly test APIs against internal standards and security policies. It can also help generate documentation, increase transparency, and even be leveraged to automatically generate SDKs in various software programming languages.
Put Governance in the API Gateway
Next, it's a good idea to place API governance controls and checks within the environments where developers are already working. For instance, most API teams utilize some sort of API management or API gateway platform. This is the ideal place to invoke fine-grained access management controls, such as policy-based authorization at the field and function level. So, consider a usable tool that allows engineers to quickly create these rulesets and iterate them as necessary.
Establish Common Guidelines
Should we pluralize nouns? What is the best resource path? There are endless variables in API design that could slow down development. So, consider creating an API design style guide with answers to these sorts of questions. Having one will bring more consistency to the API design process, helping avoid a hodge-podge portfolio with various conventions. For inspiration, check out the API Stylebook for design guidelines from organizations like Atlassian, Cisco, Cloud Foundry, and others.
You should try to reduce ambiguity on the consumer side, too. The APIToS Project, for instance, is an interesting initiative to help make creating and enforcing an API's terms of service much easier to implement across your portfolio.
Scan Your API Definitions
Another way to take the pain out of API governance is to scan your API definition file. This can highlight design issues that go against industry best practices. For example, RateMyOpenAPI.com can take an OpenAPI definition and discover flaws, such as invalid schema examples, missing components, missing descriptions, and other anti-patterns.
Now, if you have an API style guide, things get even more interesting… you could lint new API specifications against this guide. A tool like Spectral, an open-source JSON/YAML linter, can be utilized to automatically lint custom rules, helping your API designs be more conformant across an organization.
Establish a Platform Team to Promote API Enablement
Platform engineering is the talk of the town lately. The idea is that an internal platform team sets guardrails to standardize common workflows and consolidate DevOps tools and maintenance, often using internal developer platforms (IDPs). Netflix calls this a "paved road." A similar approach could be applied to API development to help developers get up and running with their APIs using pre-defined internal standards.
Document and Audit Your API Inventory
Solid API governance should ensure that no APIs are left unaccounted for. Undocumented endpoints can wreak havoc upon an organization since you can't secure what isn't visible. Therefore, document all your APIs comprehensively and consider generating an internal catalog of your services that is automatically updated. This should make your API portfolio more observable and manageable, reducing the possibility of shadow IT and zombie APIs.
Final Thought: Automate as Much Governance as Possible
API usage is expected to grow dramatically in the years to come. With all this newfound API reliance, API development can't be a wild west for much longer. New API products, especially, will need continuity and accountability to ensure things like developer experience and security are at the forefront.
Although IT governance typically has a negative corporate connotation, it doesn't have to be all "big brother." As we've shown, there are many methods to govern an otherwise chaotic mess of APIs. By setting up the right practices upfront, you can automate away a lot of governance, making things easier without stepping on anyone's toes.
