API Business Models

Knowing Where Each Version of Our OpenAPIs Are


Almost every enterprise organization I know struggles with knowing where all of their APIs are. There are always shadow and invisible APIs that exist across the enterprise API landscape, and at with the pace of change that exists within the average enterprise today, this is something that will continue being a reality for most teams. Adding to the confusion across this reality, most enterprise organizations also do not know where each version of their APIs are, and while there may have been a significant amount of work done around defining OpenAPI or other artifacts for APIs, there rarely is consistent investment in linking together multiple versions of OpenAPI definitions. Resulting in OpenAPIs being spread across servers, Git repositories, and the desktop of developers, leaving us not knowing where each version of our OpenAPIs actually reside, rendering the unavailable for use in automating change management across our API operations.

OpenAPI provide us with a machine readable way to articulate how change should be defined for each API, and the ability to automate across different versions of our APIs, but if we don’t always know where our APIs are, let alone the OpenAPI artifacts for them, and do not possess any way of articulating where each version of an API exists, we are left unable to govern and direct change across API operations. For example, if I want to detect breaking changes across a single API, I will have to have the context of where the last version of OpenAPI exists, knowing the branch, path, or specific location of each API artifact. To be able to effectively diff across multiple versions of your OpenAPI, you have to not just have common approach to versioning and storing your OpenAPIs, you have to have a common and machine readable way of articulating where they exist. OpenAPIs open up a whole other world of possibilities when it comes to discovery, governance, and managing our APIs, but the next frontier of this involves standardizing where work occurs on your OpenAPI, how change is articulated, and the development of more standards for articulating and automating around change.

Sometimes I get overwhelmed by how much work is involved with managing API operations at scale. However, recently I am seeing more light at the end of the tunnel, and more effective ways for helping us define and automate our operations. I am seeing that API governance isn’t just about the surface area of a single API, or across many APIs, and that it is also about governing how we design, develop, deploy, and operate our APIs. Which for me, helps stabilize the ground underneath my feet, allowing me to go further when it comes to API governance because every API has an OpenAPI, but also all of those OpenAPIs have an API that allows me to automate change, documentation, testing, security, and governance at scale. I am also realizing that my workspaces and repositories underneath my APIs also have APIs, allowing me to further automate and govern my operations if I have a formal approach to where API work occurs, and how APIs are deployed and operated. All of this makes things significantly less unstable and overwhelming, giving me new approaches to not just automating discovery, but also change, which from my vantage point is one of the most difficult areas we are all struggling when it comes to doing APIs effectively.

This article originally appeared here.

Kin Lane
Kin Lane is a writer, storyteller, and recovering technologists. Kin is the Chief Evangelist at Postman, and is helping share the story of how Postman is the next generation of API development environment (ADE), while also continuing to tell API stories on API Evangelist about what is happening across the API sector.

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture