Most API providers I speak with see the value of consistently delivering API infrastructure to power desktop, web, mobile, device, and network applications. Less than 10% of these providers see the API infrastructure that powers their APIs, and ultimately their applications as APIs. Meaning, these providers do not view every stop along the API lifecycle as a set of APIs, ensuring that your API definitions, design, mocking, deployment, management, monitoring, testing, orchestration, security, and documentation all have APIs, and are able to be governed programmatically. Mostly it is because they are just getting started on their API journey and / or they just don’t have the bandwidth to be able to step back and look holistically at what they are trying to accomplish.
In this truly API-first world, every architectural decision begins with a README in a Git repo, and the business, architectural, and development teams working together to hammer out a simple name, description, and list of capabilities for each individual architectural component. Once in agreement, then they can then get to work hammering out a contract for the schema, and the interfaces that are available for potential consumers. Once again, working between business, architecture, and development teams to come up with the simplest, most useful, and durable contract possible. One that will work for all stakeholders, and best represent the architectural capabilities of each component you will need to successfully operate each stop along your API life cycle.
Once there is an overview and contract in place for each architectural component, you can begin mocking, testing, and documenting it for wider potential consumption by other stops along the API life cycle. With all stakeholders in agreement over the capabilities of each architecture component, and how it will work, you can begin wiring up specific back-end capabilities which might be as simple as data and content storage, or as complex as API management, monitoring, and testing. Leveraging 3rd party services, open source solutions, or custom artisan code to fully realize each architectural component you are defining, and now developing to deliver a specific aspect of how you do APIs. Making sure you treat your API infrastructure as an API, while also abstracting way specific solutions with your own layer that allows you swap out backend solutions as you need or desire.
To help demonstrate what I am talking about, I am working on a series of stories that help me think about an API-first architectural approach to managing my API definitions. This is the most important stop along the API life cycle, and is something that touches every other stop, no matter where your journey might take you. I’ll be thinking through through how I create, store, manage, and evolve my API definitions using APIs. I have had an API for my APIs for some years now, but as I move from Swagger 2.0 to OpenAPI 3.0, and be more thoughtful about how I define event-driven APIs using AsyncAPI, as well as manage JSON Schema is use across these formats, my API API is overdue for a reworking. Additionally, I am augmenting the HTTP 1.1 layer of all of this with a Postman Collection and Environment management and automation layer, further pushing me to rethink how I’m doing things.
Next steps are to create an OpenAPI for my new OpenAPI and JSON Schema defined API contracts. Once I have this contract, I’ll spend some time thinking about the automation and programmability of the API design stop along the API lifecycle–ensuring that my APIs follows a cadre of API Design patterns I have already established. After that I will move on to mocking, testing, documenting, and development deployment and management. The goal is to actually deliver my next generation API API, but also define the APIs that drive the underlying infrastructure I am using to deliver and operate my APIs. Luckily there is a lot of markdown and YAML work as part of all of this, and it is something that I can do within a README, and here on my blog over the course of a couple weeks. The process provides me with a pretty low cost way to plan out, then ultimately deliver and communicate with others around what this API actually does.
Being able to work through every technical detail of my API infrastructure is one of the main benefits of treating my API infrastructure as an API. I can take the APIs of services and tooling I am using to deliver my API and use them as a seed for my own API abstraction layer. Taking GitHub, Postman, APIMATIC, ReDoc, Tyk, and other infrastructure providers I depend on and deliver my own API infrastructure, while also ensuring that I can orchestrate it all with my own API layer. Providing all the functionality I will need across the API life cycle as individual API capabilities that I can use to automate my API operations. Seeing my API infrastructure as just another set of API resources has changed how I view the landscape, and will has forever impacted how I interpret what an “application” is. Once I introduced the recursive loop of APIs being APIs, then “application” doesn’t mean how I apply API resources on the desktop, web, mobile, device, and networks, it also speaks to how I apply APIs to APIs–leveling up with the benefits that APIs bring to the table.
