Doesn’t time fly when you’re having fun? Somehow, a quarter of a century of HTTP APIs has flown by, as we recently discussed with Kin Lane – the original API evangelist – at the Tyk LEAP 2.0 API governance conference. However, what’s even more shocking than how old HTTP APIs are, is the fact that some businesses still don’t have API governance in place.
At LEAP 2.0, Kin shared insights from 15 years of working full-time in the API space, including through API Evangelist, as Presidential Innovation Fellow for the Obama administration, at Postman, through the Breaking Changes Podcast, as API Governance Lead at Bloomberg and now providing guidance across the industry. Governance and product development have been key themes throughout that time.
We’ve gathered Kin’s top takeaways below. Read on to discover:
- What API governance encompasses
- How it has evolved
- Key operational challenges associated with governing APIs
- How to govern change successfully
The beginning of HTTP APIs
Salesforce launched its APIs, along with its enterprise class, internet-as-a-service product, back in February 2000. The XML APIs were over HTTP. Yes, there were some other HTTP APIs prior to this, but many in the industry view this as the inception point for HTTP APIs.
Fast-forward to 2018 and Akami reported that 83% of their web traffic is APIs. Hop to 2024 and Cloudflare echoes this, at about 60-65%. All told, somewhere between 50% and 75% of all traffic is now APIs – and growth is still accelerating. But how many organizations now have API governance in place?
The evolution of API governance
These days, API governance has matured to the point that providers – well, one provider, at least – can offer a unified platform engineered for full governance, delivering outstanding business value. But what we now mean by API governance was wrapped as API management in the early days. We can look back to 2006, with the launch of Mashery, to see a strong desire to manage APIs and standardize them.
What does API governance mean today? According to Kin Lane, we can break it down into five elements:
- Usage – schema is ubiquitous across your organization.
- Specifications – JSON schema is your OpenAPI specs.
- Metadata – the human nutrients helping it make sense.
- Properties – a well-defined structure for all digital objects.
- Validation – being able to validate details of all schemas.
A schema is a fundamental building block of API operations. Enterprises have a range of schema types – database schemas, schemas powering forms and so on – but they have them primarily in the form of JSON schemas. If you’re using OpenAPI, it’s a JSON schema. It’s validated. It’s defined. You’re using it not just for your request and response payloads, but to validate your APIs in your design tools, pipelines and gateway.
These schemas often lack a lot of the metadata that people need to make sense of everything, but they do have all the properties of your digital objects; all the details you need for digital transformation. Much comes down to how well you can validate all of those schemas in motion across your enterprise, as they’re being designed, developed, requested and fed into responses.
Schemas are the foundation of your governance, so you need to have a certain amount of JSON schema literacy within your teams, as well as tooling, to be able to realize this.
Understanding HTTP APIs
HTTP APIs provide a huge opportunity. They are likely the dominant pattern in your enterprise when it comes to your digital resources and capabilities. This means, if you’re going to be successful with API governance, you need to understand all the perspectives that are at play. These include API producers and consumers (often people are both), API service providers selling tools and services, API analysts and more. Understanding the intention of all of these, and what success looks like to them, is crucial to API governance.
API governance also requires you to think about your approach – should it be design first or code first? You’ve also got to wrestle with access levels and control, which will define elements of your governance, as will your use cases and whether APIs are internal, first-party or third-party products. API governance in these three different realms means very different things.
Your API types will also impact governance. HTTP APIs span GraphQL and event-driven APIs, and with Kafka, RabbitMQ, other event driven, MQTT and gRPC APIs, there are many different flavors. But when it comes to governance, starting with the basics will set you up well, as will understanding that many aspects of governance apply across all API types. Get the basics of HTTP API governance right and you can then expand that as needed.
A word on OpenAPI
When you’re working with APIs, you’ve got to understand OpenAPI. OpenAPI is the specification you’re using to describe the entire surface area of your APIs. You can’t govern it if it’s not defined as an OpenAPI artifact.
OpenAPI means everything is on the same page, so you can talk about the same things when it comes to status codes, responses, paths and so on. OpenAPI provides a common artifact. That in itself is governance.
Additional factors to consider
Another factor to think about is that distribution requires a lot of nuance and specificity, particularly when you’re talking about centralization versus federation. What are you talking about federating – governance? The gateway? The development of APIs? These conversations, encompassing platform, governance, center of excellence and more, are an important piece of managing APIs.
The final moving part in all of this is, of course, the human experience. None of the above matters without this part. It includes not just the API consumer experience, but the experience of the API producer, the design/code first experience, the experience of those involved in architecture, compliance, security… all the touchpoints at every stage of producing and consuming APIs. What do they understand, and how do they see things?
Governance processes
When you hear the word “governance”, certain other words usually follow hot on its heels – “rules” being chief among them. You have spectral rules, sometimes some custom rules and now vacuum rules, which are compatible with spectral rules. These are little rules that lint for things in OpenAPI – things that should be common, like HTTP status codes, path casing and parameter casing. Rules are how you define these little bits and bytes, but ultimately, it’s not the rule that matters – it’s everyone working towards and creating those rules.
When you apply rules to your schema, you shouldn’t just apply them to your OpenAPI artifacts; there’s no reason not to use those same rules outside of your OpenAPI to link the completeness, the quality and the overall bar for your schema. And, of course, you apply them to your OpenAPI specs as well, using them to govern the design of it and how complete, robust and ready your APIs are. You can also expand the rules to wider API operations, governing and guiding everything along the way.
On the subject of rules, it’s important to consider automation. Common sense applies here, rather than automation at all costs. After all, rules are nothing without human coordination, awareness and understanding, so automation should be approached with caution.
Reviews are important too, but they’ve got to be done in person and in a self-service way that supports ongoing motion. Otherwise, reviews can quickly become a bottleneck.
Finally, you’ll need to align your rule set with the wider organization through ongoing dialogue. It’s not a set and forget matter. You’ll need weekly reviews of your policies, rules, automations and processes, adjusting them perpetually to align with the wider enterprise strategy.
Operational governance challenges
Whether you take a centralized, federated or any other approach, you’ll need to bring visibility into the lifecycle and the platform beneath. Bringing more visibility for teams where and when they apply those rules is key.
Another challenge is that, in governing all the technical details, you don’t govern enough of the business details – all those downstream impacts that you need to govern as well.
Standardizing the properties of your API operations is another issue. This encompasses a whole range of considerations, from whether your sandboxes are standardized, to whether you have documentation, to whether there’s SDK delivery generation. You’ll need to think about the tools, clients, workspaces and other resources developers are using. Then, with all of this in mind, you need to think about how you’re standardizing your API operations to ensure they’re consistent across teams, not just the APIs.
On the operational side, you’ve also got to acknowledge that it’s not a case of centralized versus federated. It’s both. So, you need to have that conversation operationally – where things should be and what matters most.
Keeping your objectives in mind is the final operational challenge. Why is your enterprise actually doing APIs? There could be multiple reasons, so you need to be explicit about those objectives and ensure you know the business reasons behind your APIs. Because that’s what you need to prioritize when it comes to API governance.
Governing change
Change is inevitable, meaning you need to embrace it while you’re strengthening and maturing your governance. If you don’t, things will become exponentially messier and harder.
You can tackle this head on by scoping precisely what level of change is happening. Are your APIs changing or your operations? Is the leadership team changing and with it your business goals? Being honest about the changes that are occurring and planned will help you govern smoothly throughout them.
Specification change can also occur, meaning businesses could be using anything from Swagger to OpenAPI 3.1.0. Your enterprise could be using the latest drafted JSON schema, or it might have five or six different versions in place.
And what about source? Do you have a central source control for every API? Do you have a source of truth? If you don’t, life will quickly become much more difficult. You need to have a source of truth that you govern and ensure is consistent if you’re going to help manage change.
It’s also important to think about how you signal change and why. It could be date-based, for example, or semantic based upon breaking and non-breaking patches. Or both! Understanding the signals and how to communicate them is crucial. After all, the way you approach and communicate changes to your APIs can make a huge difference to how successful those changes are. It’s the whole reason you use version control.
API governance evangelism
The last piece of API governance is evangelism. This applies whether you have internal or external APIs. It covers your content, artifacts, channels and face-to-face concerns.
In terms of content, it’s about making sure that all your building blocks are known: Your documentation, blogs, videos, use cases, webinars and so on. All of those artifacts need to be forkable and executable – it’s part of the API and the hands-on work around it, from OpenAPI and collections to Jupyter Notebooks and sandboxes. All produced in motion in an ongoing way.
A lot of businesses create centers of excellence, which are great – provided you keep them up to date. Out of date GitHub repos, style guides and Confluence pages aren’t helpful. Just like the rest of your rules and policies, your content and artifacts need to remain in motion – they need to be bite-sized, meaningful, useful and applicable in the moment.
Also important is understanding the best channels to engage your audience. Whether it’s on Slack, Teams, Confluence or anything else, you need to connect with those producing and consuming APIs via their existing channels. That’s where your content needs to be, in an ongoing, self-service way.
Layered over the top of this are face-to-face interactions. Having clear office hours and regular meetings supports these meaningful interactions. Discussions on the API, governance, policy and more need to be ongoing to support the relevant, contextual, continual motion that’s so crucial to successful governance.
Focus on your HTTP API governance
Underpinning all of this is the need to avoid distraction. Mobile, web, single page apps, bots, AI, different protocols… there have been many waves of distraction over the past 25 years of HTTP APIs and there are doubtless many more to come. But none of that should distract from prioritizing your API governance.
Focusing on your HTTP APIs means getting your basic house in order, focusing on your schemas, your APIs and getting governance in motion. It means getting a handle on your operations and having an effective strategy for managing change, while ensuring evangelism is a core part of everyone’s approach. This is what will support you to successfully govern your HTTP APIs.
Keen to know more? Then check out these enterprise-level resources to help your business excel.
