As APIs, and an API First strategy, gain more recognition throughout enterprises as important factors in digital transformation, we’re seeing a rush to plan, design, and build new APIs at scale. Proper API governance is essential to ensuring your APIs are:
But what exactly is API governance, why do you need it, and what are proven best practices for enforcing it?
What is API governance?
API governance is the practice of applying common rules relating to API standards and security policies to your APIs. It also quite often involves designing your APIs based off a common data model of approved reusable resources/model objects (this is a best practice in itself which we will come back to later). Finally, governance can be used to ensure your APIs are sufficiently enriched with metadata for them to be easily consumed by a wider audience, both within your enterprise (e.g. product managers), and externally (e.g. partners).
The goal of API governance is to ensure proper standardization of your APIs so that they are discoverable, consistent, and reusable.
Who needs API governance?
Simply put, API governance is important for any organization implementing an API First strategy, where APIs are core to their transformation to a digital business. It’s also vital for anyone planning to, or already implementing a distributed microservices environment.
There’s one use case in particular where API governance is absolutely critical — large enterprises. This is because they require 1000s of consistent, secure, and reusable APIs representing both Business and IT functions, instead of a handful of well-documented public APIs in an API portal.
There’s also a regulatory/compliance aspect to the need for API governance. One example is the Open Banking Implementation Entity (OBIE)’s Open Banking Standards in the UK for the big 9 banks. Admittedly, the standards are in an early stage of maturity, but the trend of regulator pressure on organizations to enforce proper API governance and standards, and to be able to demonstrate that they are doing so, is one we expect to see grow dramatically in the coming years.
API governance… no longer the Elephant in the room?
Traditionally, API governance gets a bit of a bad rep and has often been viewed as slowing down development. This is primarily due to APIs being manually written by developers, often with governance as an afterthought — and so governance has always been hard to enforce — relying on remembering to apply the rules, hard to check against and resolve without manually massaging the code.
On top of that, there are different architectural styles of APIs (think SOAP vs REST vs GraphQL vs AsyncAPI etc.) each with their own recommended coding standards and design patterns to keep up with, and often subsets within that depending on the profile of the API you want to design — that’s a lot of rules to remember!
Thankfully, there is a newer body of opinion, supported by great tooling, that applies governance upstream in the API lifecycle. If implemented in the correct way, and by following the best practices below, API governance can in fact speed up your development of APIs at scale, and ensure you’re getting the best business value out of your investments. That’s regardless of the type of API you’re designing.
8 API governance best practices
1. Have one set of enterprise-wide API governance rules
This sounds like an obvious one, but it’s important to have a set of governance rules that are defined globally instead of only on a LoB/individual group basis. By this we mean not only to adopt basic coding standards (e.g. the OpenAPI Specification), but also those based on what matters to the business, for example:
- how you want to apply said generic standards (e.g. the OpenAPI Spec) in your enterprise in your code
- important metadata fields which should always be documented e.g. owner, lifecycle state, the capability the API supports, taxonomy
- the API security protocols which are applicable to each type of API
- access control rules for who can do what with your APIs
You also want all your governance rules for different architectural styles of service (e.g SOAP, REST) in one place. If they are all centrally located and maintained, everyone using them in your organization has one source of truth.
2. Manage your APIs as abstracted Designs in a holistic service catalog
There’s two parts to this best practice. The first is that if your APIs are held as abstracted Designs instead of code, with the technical details (e.g. payloads, parameters, and headers) held in associated Specification(s), applying governance rules becomes much easier to both bake-in and apply throughout the lifecycle (see later best practices for more on these).
The second is that if they are held as part of a holistic service catalog, with mappings/lineage/dependencies all documented too, and aligned to taxonomies, it’s much easier to visualize and rationalize your APIs. You gain insight and control into where they are, who owns them, who’s using them, where the flow of data is etc. Obviously, this is particularly helpful for the regulatory aspect of API governance we discussed earlier.
Continue reading the best practices for API governance here: https://www.digitalml.com/api-governance-best-practices/
Looking for a solution to help you implement API governance best practices? The ignite platform from digitalML provides a holistic service catalog with API lifecycle focusing on Plan, Design, and Build. ignite provides extensive API governance features including baking-in governance rules (including API standards, security policies, and applying rich metadata to APIs and Services), full versioning, and designing off a common information model. For more information on ignite visit our platform page.
About the Author
Gemma is a Marketing Manager at digitalML. She has a keen interest in digital strategy and the best ways to merge people, process and technology. Her experience spans Marketing and Client Services in the Technology and Financial Services industries.
Originally published at https://www.digitalml.com.