API Dimensions That Ground the Conversation

I am perpetually working on what I consider to be the essential API dimensions that ground how we talk about APIs. While having a common definition of the API lifecycle, as well as a clear list of roles and stakeholders involved across the API lifecycle is essential–these dimensions or focused on how we “see” and invest specifically in our APIs. In my experience, there are many ways we talk past each other and introduce friction into our discussions about how to do APIs well. While there are other dimensions not reflected here, these reflect on the areas I find myself talking with enterprises about the most, and that I am getting more opinionated on to help ground my conversations.

  • Presence - New or Existing
  • Approach - Design-Led, Prototype-Led, Code-Led, or Proxy-Led
  • Motion - Sustainment or Evolution
  • Pattern - REST, GraphQL, SOAP, gRPC, or Websockets
  • Contract - OpenAPI or AsyncAPI
  • Schema - JSON Schema or Protocol Buffers
  • Availability - Cloud or On-Premise
  • Access - Private, Partner, or Public
  • Maturity - Alpha, Beta, Release Candidate, or Stable

Once you answer these questions about an API, the lifecycle, governance, and communication as well as collaboration with teams become a lot more coherent. These dimensions inform the lifecycle, shape governance, and define the relationship between API producer and consumer. Grounding API discussions across these dimensions would reduce friction and frustration across operations significantly. Next, I am looking to speak about these dimensions in business terms as opposed to the very technical lens they are presented in currently.