API conversations are hard. Not because APIs are hard, but because they are virtual and difficult to see, and there are multiple perspectives and scopes existing across individual APIs, and the APIs that exist across an enterprise, as well as the industries they operate in. One of the most interesting aspects of doing APIs I have witnessed in the last 15 years of API hustling, is that it is very easy to talk past each other, with one person focused at one level and the other at another level. Understanding the perspective of who you are talking with, and possessing a common understanding of the API landscape that is ideally machine and human readable, is the only way to move things forward in this chaotic landscape.
It is easy to be talking about a specific property of an OpenAPI for an API, and then have someone switch to talking about the lifecycle surrounding the implementation of the API described by the OpenAPI. Sometimes people do it to deflect, but mostly it is unintentional and just reflects each person’s vantage point within API operations. There are many moving parts involved with producing and consuming a single API, let alone what happens across all of API operations, so it makes sense that we’d struggle for precision in what we are talking about. APIs are virtual and very hard to see, so ensuring we are on the same page isn’t easy, and depending on where people and organizations are in their API journey, things become exponentially more difficult.
Grounding API conversations is why I believe in schema, and think JSON Schema is the most important API specification out there. I believe in the use of JSON Schema for business and for technical folks involved in the conversations. Getting a business stakeholder to have a conversation around a schema is actually just as difficult as it is to get a technical person to have a conversation around a schema–just for different reasons. Business folk shy away because of what they perceive as technical complexity that is over their head, and technical people shy away because it is a technical configuration object, not something that contains bits and bytes about humans that need discussing. Both directions, a full schema like OpenAPI can ground conversations, all the way down to conversations around a specific response for a specific API operation.
Another thing that significantly impacts API conversations, but in the negative direction, is what I consider “other tooling”–meant as a verb. You are having a conversation with someone about an API, and they “other tool” ya. You are walking through a schema that you have worked on for days, even converting it to YAML to make it more readable, and the person you are talking to suggests taking things to a Word document, Jira, or via a spreadsheet. Where sometimes this may add more organization and structure, it often is a deflection from actually doing the world to get on the same page. A missed opportunity, or more deflected opportunity. This is why I prefer keeping things grounded to a single schema focused on the surface area of the API, or on a specific aspect of the API lifecycle–minimizing switching scope or tools to help keep the conversation moving forward.
I have been working harder to quantify where someone is at in their API journey and what their role is in producing and consuming APIs, so I can make sure and speak at the right scope and level. There are very few people who can speak to and care about the highest levels of API strategy, lifecycle, and governance, and of those, there are few who can also go down the rabbit hole at each stage of the API lifecycle, and properly put on your API consumer as well as an API producer hat. You have to be able to do it all if you are defining strategy and shaping an API governance program, and driving conversations across many different stakeholders. I have stopped believing everyone should care about the big picture, and spend most of my energy focused on making sure individual and team conversations are at the right scope and just don’t talk past each other.
Getting people on the same page when it comes to producing APIs is the most important aspect of API governance. You’ll hear me say this repeatedly in the coming months. In a world where people are virtual and multi-tasking and possess different perspectives and competing interests, grounding conversations using JSON Schema, APIs.json, OpenAPI, and other common or community schema can have a massive impact on velocity and direction. This is true for business and technical stakeholders, despite what each side of the coin may believe. Human and machine-readable schema is how we get more precise about the scope of policies applied across our API operations, and stop talking past each other. Otherwise it is just noise and chaos across a sprawling API landscape.
