There is a lot of talk today about platforms. A topic that has evolved over the years, beginning with waves of startup technology platforms, and now followed by everyone thinking they are a platform. There is a lot of focus within enterprise organizations right now to centralize a platform, with a significant portion of that work focused on what many consider the API platform. While my definition of an API platform might not exactly match the definition popularized in this moment, there is a lot of overlap. Like most of my work, I am focused on the fundamentals of an API platform, and understanding what is essential to HTTP API operations, and working real hard to get a handle on the basics, ensure teams are aligned, and this is something that begins with an API contract dedicated to defining your API platform.
As with most strategic API efforts I begin with an APIs.json contract. To define my API platform I fire up and APIs.json, add metadata to reflect the platform work I am doing and then add APIs for each of the pieces of infrastructure, tooling, and services I depend on for my API platform, for both the engineering and the business side of things. It may seem simple and trivial, but just having a manifest of metadata for the Infrastructure, tooling, and services I depend on, goes a long way towards stabilizing how I use these solutions, which echoes across API operations. If you have a list of the Infrastructure, tooling, and services you depend on, you have a better idea of what is involved in operating your API factory floor, but then it makes it easier to also communicate what is available to teams who are producing APIs.
Another significant aspect of properly defining your API platform that goes over the heads of most people involved with API operations, is whether or not you are building your platform, or building on the platform of a 3rd-party service provider. While it may seem like a trivial detail to people operating in the enterprise, it is a centerpiece of the strategy of venture capital and API service providers who strongly believe you are building on their platform. If you do not take the lead in defining and building your own platform, with a serious strategy for how you will plug 3rd-party infrastructure and services into that platform, you are building on someone else’s platform. Over time you will become more beholden to these platforms you operate on, slowly outsourcing your intellectual property, value, and control outside of your enterprise. Firing up an APIs.json and defining all of the Infrastructure, tooling, and services you depend on is the first step in asserting control over your future.
When defining your platform starting with the basics like the name, description, and tags for the API service providers and tooling you depend on. Then move on to tracking links to documentation, logins, dashboards, pricing pages, licensing, and terms of service. Once you get some momentum you can begin adding OpenAPI definitions for the APIs they make available alongside the Infrastructure, tooling, and service GUI or CLI that came with the purchase. Once you have the basics nailed, you can begin actually automating more around the platform resources and capabilities you depend on the most. As you get more familiar with what resources and capabilities are available, as well as which resources and capabilities would help teams producing APIs the most, you can begin building in guard rails using the APIs your Infrastructure, tooling, and service providers offer—then publishing and injecting these guard rails into the IDE, CLI, Postman workspaces, and the other places that your teams are working on a daily basis.
With a solid understanding of the Infrastructure, tooling, and services you use to operate your API factory floor, and a strong understanding of the API resources and capabilities they offer, as well as which ones your teams will need in their work—you can begin automating on top of your GitOps-driven approach to API governance, weaving Infrastructure, tooling, and service APIs into the CI/CD pipeline and web hooks of your Git workflows. This is where you will begin to equip and guide your teams, blending API governance seamlessly into their IDE and Git workflows. This is the holy-grail of why you want to define your API platform. Sure you can do this in an ad hoc manner, but defining your platform properly means that you have a high level view across all the Infrastructure, tooling, and services you depend on, along with a rich understanding of their resources, and how they will impact your teams in their work. This takes work. This does not happen overnight, and begins with doing the work to properly define your API platform, and getting a handle on the fundamentals of how your API operations works or doesn’t work today.
