In this post:
- What is API governance?
- Who needs API governance?
- A fresh approach to governance can actually speed up development
- 8 governance best practices + benefits
- Further governance resources – deep dives and assessing your maturity
As APIs, and an API first approach, 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:
- Discoverable – APIs are easy to find and use by the entire organization
- Complete/Consistent/Compliant – APIs are high quality and deliver reliable consumer experiences
- Reusable – APIs can be easily reused/updated/extended
- Secure – so that your data is secure and you’re complying with regulation
In fact, Forbes are now stating that “the strategic importance of API governance cannot be underestimated”, and that API governance is a key part to an enterprise’s competitive edge when it comes to digital.
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 and guardrails relating to API standards and security policies to your APIs. These rules are applied through checks and validations, for e.g. checking API basepath uniqueness.
It also 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).
In practice, we often see enterprises using an API governance model encompassing a multitude of rules, patterns, standards and policies – more on what’s in a great governance model in this other post.
The goal of API governance is to ensure proper standardization of your APIs so that they are complete, compliant, and consistent, and therefore easily discoverable 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. If you’re a large enterprise, you’re likely scaling to 1000s of APIs that encapsulate your business capabilities. Done in a properly governed way, you end up with a portfolio of business building blocks that can help differentiate you digitally, 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. We’re also seeing a growing trend of internal and ad hoc governance reporting, especially for API security and provider/consumer relationships.
API governance… no longer the Elephant in the room?
Traditionally, API governance gets 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 exclusively on API style guides and manual review processes.
There are some further pain points that can make governance daunting too:
- 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
- Flexibility for exceptions are needed – a set of rules for one use case may not be applicable for another
- Enterprises are running distributed runtime environments with APIs at different lifecycle stages – again the rules for one lifecycle stage may be different for another, plus approval workflows are needed
- Reportability – how do you easily show what’s in/out of compliance with all of these complexities?!
Thankfully, there is a newer body of opinion, supported by great tooling, that applies governance upstream in the API lifecycle. What’s more, it’s automated and self-service nature! 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 a centralized set of enterprise-wide API governance rules…
This sounds like an obvious one, but it’s important to have a core set of governance rules that are defined globally and adopted across the enterprise. 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:
- Ensuring API uniqueness
- Checking important metadata fields which ensure discoverability and reusability e.g. owner, lifecycle state, the capability the API supports, classification
- Access control rules for who can do what with your APIs and when
2….. But enable reportable exceptions to ensure flexibility and responsiveness
Your governance model needs to be applied flexibly. Different lines of business (LoBs) or regions may well need their own rule sets.
The way governance is applied and calculated also depends on the type of API (e.g. a legacy SOAP service will need different rules to a new business capability REST API). Other factors for exceptions include downstream target platform, technology types etc. Responsiveness is synonymous with flexibility, and governance models are no different.
Within our customer base, we’ve seen exception pathways for API governance including:
- Needing a certain API security policy based on LoB or taxonomy classification
- When an API design meets a certain condition, a particular error response (which has been defined in the canonical model) is needed
- Based on HTTP Method Type, certain headers and/or response codes are required
If your governance model is centrally located and maintained, everyone using them in your organization has one source of truth. It’s also easier to ensure reportability and manage exceptions at scale.
3. Automate governance checks and validation for speed an enablement
Self-service governance means empowerment and enablement over enforcement, and helps increase productivity and speed. Look for a platform that replaces API style guides and rule sets held in spreadsheets etc. and manually reviewed with an offering that automates checks and validation for all your API types. Even better if violations can easily be addressed directly in the platform without having to manipulate the code. We recently held a webinar on how our ignite platform can enable self-service governance at scale – download it here for free.
4. Manage your APIs as abstracted Designs in a Holistic 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 catalog, with complexities that come with a mature program captured also such as:
- API mappings, orchestration, transformations
- provider/consumer dependencies and lineage
… while also properly organized and classified, 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.
5. Use an information model to plan, design, and build your APIs
Many 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.
6. Apply governance at all stages of the API lifecycle
API 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. You’ll also be ensuring the outputs are all properly standardized and reliable.
7. Implement robust API versioning
APIs 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. Supporting major, minor, and patch versioning is best practice here.
8. Ensure your API governance rules are met before an API can be deployed
Deploying 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. Doing so ensures your APIs are complete, consistent, and compliant, and delight your internal and external consumers!
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.
Further API governance resources for enterprises
Here at digitalML, we love all things API governance. By applying the 8 best practices we’ve discussed in this blog, your enterprise can go faster with market leading initiatives such as:
- Supporting top-down and bottom-up API development including enabling roles such as Leadership, Business Analysts, Product Owners and Developers
- Drive culture shift and adoption of an API and event first, product-based mindset
- Quick and accurate regulatory and internal reporting
- Accelerating innovation through recombining existing functionality exposed as enterprise-grade APIs, Services, and Events
To continue your journey on how to implement these API governance best practices, we recommend the following resources:
- Article – Enable multiple roles through effective governance
- Article – What’s in a great governance model
- On-demand Webinar – The tried and tested approach to self-service API governance at scale (or here’s a brief takeaway piece if you don’t have time to watch in full!
- Governance Maturity Assessment – We’ve taken benchmarks from our enterprise customers to help you assess how mature your API governance approach is currently
