In this post:
- What is API governance?
- Who needs API governance?
- A fresh approach to governance can actually speed up development
- 9 governance best practices + benefits
- How the ignite Platform delivers mature API governance
APIs (application programming interfaces) are continually growing in adoption as a way to connect applications and speed up digital transformation. With the proliferation of APIs, proper API governance is now more important than ever; ensuring your APIs are:
- Discoverable: APIs are easy to find and use by the entire organization
- Complete, Consistent, and Compliant: APIs are high quality and deliver reliable consumer experiences
- Reusable: APIs can be easily reused/updated/extended, and composed together
- Secure: so that data is safe, risk is minimized, and you’re complying with regulation
- Collaborative: well thought-out and well-documented so that everyone in your ecosystem can understand, use, and collaborate on them.
It’s no wonder therefore that Forbes state “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. Done right, it provides your developers (and business roles) an easy and fast way to make the right decisions while they’re designing, developing, and managing APIs. What’s more, API governance can help increase the value of the functionality you’re exposing.
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 defining and applying standards, policies, and processes that ensure your APIs are standardized, reliable, and secure. Fundamentally, API governance provides the guardrails that result in great APIs, and is a key component of a mature API management program.
Policies and standards are applied through checks and validations, for e.g. checking API basepath uniqueness. This can either be done manually or automatically.
Good governance also often involves designing your APIs based off a common data domain 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, with subsets of rules for different API protocols, patterns, and use cases.
The goal of API governance is to ensure proper standardization of your APIs so that they are high quality, reliable, 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 transformation and treated as strategic business assets.
There’s one use case in particular where API governance is absolutely critical to get right. That’s large enterprises. You’re likely already working with 100s-1000s of different API categories and types. These APIs are exposing your business capabilities and IT functions, and with the help of good governance provides you with a portfolio of reusable business building blocks ready for consumption by your internal, partner, and customer consumers.
There’s also a regulatory/compliance aspect to the need for API governance. The best known example example is the Open Banking Implementation Entity (OBIE)’s Open Banking Standards in the UK, but API-related legislation is ever-growing across the globe. We’re also seeing a growing trend of internal and ad hoc governance reporting, especially for API security and capturing and tackling the looming threat of API sprawl.
API governance… overcoming the bad reputation
Traditionally, API governance is viewed as a four-letter-word and handbrake to development speed. This is because governance guardrails have been hard to enforce without a rigid manual approval process and centralized control. Not to mention the time and effort needed for developers to adhere to API style guides while they’re creating APIs (and so understandably governance is often an afterthought).
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 (e.g. a business capability API vs a one-off point-to-point integration).
- 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 for each are needed.
- Reportability: how do you easily show what’s in/out of compliance with all of these complexities?! Governance without transparency is not good governance.
Thankfully, governance approaches are maturing, supported by great tooling that aligns APIs to your governance model earlier in the API lifecycle. What’s more, it’s automated, flexible, democratized! 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.
9 API governance best practices
1. Have a centralized set of enterprise-wide API governance rules…
This sounds almost counter-intuitive given what we’ve just discussed. But there will always be a need for 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 build in flexibility and responsiveness
Your governance model needs to be applied flexibly for it to be effective and adopted. Different lines of business (LoBs) or regions may well need their own rule sets for example, and there will always be exceptions needed.
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, and where you’ll be exposing your APIs (e.g. an internal Developer Portal vs public Marketplace). 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 with all it’s exception pathways and different rule sets 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; transparency is so important for stakeholders and users having faith in your governance process.
3. Automate governance checks and validation for speed and enablement
Self-service governance means empowerment and enablement over enforcement, and helps increase productivity and speed. Look for a platform (like ignite) 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 and category. Even better if violations can easily be addressed directly in the platform without having to manipulate the code. This speeds up your governance process and frees developer time up for business logic and other big brain thinking that makes your APIs really valuable and world-class.
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. This type of catalog unifies all your APIs across different patterns, platforms, and lifecycle stages. A holistic catalog also captures and manages complexities that come with a mature API program:
- API data mappings, orchestration, transformations
- provider/consumer dependencies and lineage
… while also properly organized and classified, making it much easier to rationalize your API landscape. 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. Build in data consistency through reusable domain models and components
Many large enterprises either have, or are working to move away from large clunky canonical models in API development. Instead, they’re adopting domain models of reusable data components to build in data consistency especially in the APIs’ payloads. in the SOA days). Developing APIs in this way is recommended because 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 – especially if you’re shifting left to focus more on Plan, Design, Build, and Run – you’re going to prevent these roadblocks and help speed up time and volume to market, without sacrificing API quality.
7. Implement robust API versioning
APIs often need extending and/or modifying, or sometimes deprecating, and API versioning is therefore crucial to keeping track of this. It’s important to align all versions to your governance model and guardrails.
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 and adding to the growing danger of shadow APIs. 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 your API has an appropriate security policy applied and all your defined “must” violations are addressed before it can be transitioned from UAT to Production environments. This is of course important for effective API security too, and with API attacks up by 400% in the last 6 months alone, security is now more important than ever.
9. Education and training to reframe the API governance mindset
It takes time to move away from the negative connotations of “big G” API governance, which is why it’s worth investing in educating stakeholders in your enterprise to the modern and mature approach of governance that’s automated, flexible, and democratized. You can do this in a formalized way such as establishing an API governance centre of excellence (CoE), by sharing the plethora of great governance resources now available internally, or by implementing API tooling that makes governance a breeze: the list really is endless. But it’s worthwhile demonstrating that governance done right delivers a genuine competitive advantage and accelerates digitization.
How ignite supports mature API governance for enterprises
Here at digitalML, we love all things API governance. By applying the 9 best practices we’ve discussed in this blog, your enterprise can go faster with market leading initiatives such as:
- Delivering differentiated products and services directly where your customers are
- Supporting a cross-functional API ecosystem
- Drive culture shift and adoption of an API 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
For the next step in your API governance maturity journey, here’s how our ignite Platform can help deliver automated, flexible, and democratized guardrails
