Enterprise API Governance Best Practices

As APIs, and an API first approach, continue to become more ubiquitous as a means to delivering all things digital, enterprises are focusing heavily on their API governance strategy for quality 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 regulations

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 are the best practices for enabling governance at scale, when you're planning, designing, building, and running 1000s of APIs? Good governance means more than just an API style guide, it should be transparent, automated where possible, and result in empowerment over enforcement.

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 reliably expose 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 API development being a manual process, 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. This puts a handbrake on speed, and often results in error-prone APIs with a bad consumer experience.

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 have an on-demand webinar on how our ignite platform can enable self-service API 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 ensuring API organization and classification, 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.

Here at digitalML, we love all things API governance. By applying the 8 best practices we’ve discussed in this article, 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

This article was originally published on digitalml.com