What is API Governance? 8 Best Practices for API Governance Success
February 4, 2020|
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 rulesThis 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
2. Manage your APIs as abstracted Designs in a holistic service catalogThere’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.
3. Use an information model to plan, design, and build your APIsMany large enterprises either have, or are working to build, information models (known as canonical models in the SOA days). Planning, designing, and building your API methods off a model is recommended because by doing so you are using approved model objects and resources which standardize enterprise information in predetermined structures. This helps with API governance at speed as it’s increasing standardization and reusability of your APIs, while bypassing the slow process of developers having to constantly define common structures over and over.
4. Apply governance at all stages of the API lifecycleAPI governance has traditionally had the tendency to cause roadblocks in development – when things have been overlooked early on but become a bigger issue later in the process. If you can ensure your API governance rules are applied at all stages of the lifecycle – i.e. throughout Plan, Design, Build, and Run – you’re going to prevent these roadblocks and help speed up development, while ensuring the outputs are all properly standardized.
5. Bake-in your API governance rulesThis best practice is key for overcoming governance being that Elephant in the room we mentioned earlier. Having to rely on your developers to manually apply your API governance rules, standards, security policies etc. in their code is no fun for anyone, and not feasible when you’re developing APIs at scale. You may also have different levels of governance to be applied e.g. the Swagger violations levels of “must” vs “should” vs “may”, and rules around which levels need to be met before an API can transition to a certain state (e.g. UAT → PROD). That’s near-impossible to enforce if API governance is a manual process!
Therefore, API governance rules need to be baked-in, automatically applied and validated against, with a simple way to rectify violations, without having to spend time digging in the code. By doing this, you’re minimizing human error, speeding up development time, and ensuring that all your APIs are standardized and reusable.
6. Implement versioningAPIs often need extending and/or modifying, or sometimes deprecating, and versioning is therefore crucial to keeping track of this. It’s important to apply your governance rules to ALL the versions, to ensure they’re all standardized and properly documented. Governance can also help determine if a change is backward compatible or not, so it may be possible to enforce major version change if an API version is not backward compatible, and therefore prevent breakage when deployed and used by applications.
7. Ensure your API governance rules are met before an API can be deployedDeploying un-governed APIs, or APIs with governance violations, even into a sandbox environment, is detrimental for large enterprises; costing time and money. You want your enterprise’s API governance rules, as well as generic architectural type standards (e.g. OpenAPI Spec), to be validated against and any violations resolved while you’re still in design-time.
An example of this would be ensuring that all the “must” Swagger violations are addressed before an API can be transitioned from UAT to Production environments.
8. Apply governance rules to your Brownfield services tooIt’s one thing to ensure all your shiny new Greenfield APIs are properly governed, but there’s huge value in applying the same standards to your Brownfield (e.g SOAP web services). Doing so provides insight into the overall state of your legacy assets, helps identify high-priority targets for modernization, and speeds up regulatory and compliance-based reporting.
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.