I am perpetually fascinated by how people “see” APIs based upon their role, experience, and how they are incentivized to work on APIs. For the last decade plus, my strongest way of assessing where some is located in the API realm and how they “see” APIs, is the OpenAPI specification. This open-source JSON or YAML specification for defining the surface area of an API has become the best way to understand if you and someone else you encounter on your API journey are on the same page, and presents the greatest opportunity for you to get on the page, and assess when someone will be willing to get on the page with you.
An OpenAPI specification becomes a fun house of mirrors when it is published to a GitHub repository by an API producer. There is a lot going on in a public GitHub repository containing an OpenAPI, as documented in my ongoing series about how GitHub is used to manage OpenAPIs. You see the technology, business, and politics of API present in these repositories and with all of the available (or not) elements. To understand more about what I am talking about, and how OpenAPI reveals so much about API producers and consumers, we’ll need to take a short trip back to 2011, to explore how OpenAPI has evolved over the years, with all of us changing along the way.
In 2011, Tony Tam and the Wordnik team shared Swagger with the world, demonstrating how a single JSON API specification could be used to configure and power interactive API documentation, mock servers, and generate client SDKs. It forever changed how we talk about APIs. These three very separate lifecycle elements were made easier to deploy and keep up to date through collaborative evolution of a single JSON configuration file, keeping your docs, mocks, and SDKs all in sync. This allowed teams producing APIs to focus more on the value their APIs were delivering and less on the documentation, mock servers, and generation of code for consumers, allowing them to iterate faster, and better meet the needs of consumers, while staying ahead of the competition.
By 2013, Swagger was being copied by other API service providers, resulting in Mashery I/O docs, API Blueprint, and RAML. The company behind API Blueprint saw the potential of a machine-readable specification, docs, and mocks when it came to shifting API development left, and introduced the world to API design-first. Apiary convinced thousands of API producers to design and iterate their APIs with their internal or even external stakeholders using a machine-readable spec, and generated docs and mocks. Apiary evolved Wordnik’s approach with Swagger, docs, mocks, and code generation, further ensuring teams whho were producing APIs were on the same page, but they were also on the same page with their consumers. While API design-first hasn’t always lived up to the hype, it has forever changed how we see the API lifecycle, and deliver our APIs, whether you are code-first, design-first, or prototype-first.
As we approached 2016, Swagger was put into the OpenAPI Initiative, being reborn with a new name, major version upgrade, and the ability to be defined as JSON or YAML, making the API specification more approachable by business stakeholders. By this time source control like GitHub had become commonplace, and CI/CD was making the API lifecycle more repeatable. GitHub made the API lifecycle more collaborative, iterative, and consistent, and when you combine with a design-first approach out in the open where your consumers can join in on the fun, new things begin to happen. A GitOps approach to managing a public or private API helped ensure API producers and consumers were on the same page, with everyone joining in on iterating an API until the right API design is negotiated in any given moment.
With the injection of OpenAPI into source control and the CI/CD pipeline we saw the expansion of using OpenAPI to generate tests that could ensure the quality of APIs as part of the build process. Teams also realized they could use the OpenAPI to configure the gateway and shape the API runtime. OpenAPI was being baked into leading API gateways and management solutions, allowing you to deploy your API using OpenAPI or publish documentation and export an OpenAPI from your gateway. This allowed OpenAPI to simultaneously move left and right in the API lifecycle, acting as a source of truth for the technical details of an API from define to deprecation-—aligning teams producing APIs, but also aligning their forward motion with API consumers and their applications.
With the number of APIs dramatically increasing and the number of teams producing APIs, enterprises begin seeing the need to govern and standardize their API across teams, going beyond what the JSON Schema for the OpenAPI specification could validate. In 2017, an open-source OpenAPI linting format called Speccy emerged from a WeWork team, and becoming Spectral in 2018. Since then we’ve seen enterprises like Microsoft, IBM, Adidas, and others begin publishing and sharing their Spectral rulesets alongside their OpenAPI definitions. Spectral adds another artifact to the stack that helps teams producing APIs get on the same page, align across the enterprise, but also within industries and the wider tech space. If you look at the most progressive and productive APIs today, they center around an active GitHub repository, with all of the supporting elements to help empower and automate everyone involved.
There are other elements to this conversation, the role Postman Collections have played, but I am a petty bitch so I’ll leave that out of this story. However, by 2022 everything I talk about is a given when it comes to API conversations, and as I begin doing the Breaking Changes podcast, these areas are the foundation of conversations, and the top two areas of conversations across almost 150 conversations were:
- API Governance - How do we scale and automate governance for APIs.
- Products - How do we repeat everything here but with the business side.
This timeline represents where enterprises are in 2024. Some enterprises and individuals at the beginning of this journey, some are somewhere along the way, and others are heavily investing in Spectral rules to govern their APIs at scale, and introduce other properties and artifacts to bring more alignment with business through the productization of APIs. The YAMLization of the API lifecycle has made things more accessible to business stakeholders, and headless APIs, GitOPs, and using source control as a repeatable CMS has been laying the bridge between IT and business for a number of years now. Teams producing APIs, as well as those consuming, just need to do the work to understand where the value in this journey exists for their operations, and collectively do what is required to perpetually align things and increase velocity.
Now, back to the opening of this story and how people “see” APIs depending on their role and incentives. Depending on where you are on this journey you will see the value of OpenAPI lying in different portions of this narrative. For most, the value of an OpenAPI lies in the documentation-—Swagger UI and ReDoc. The next biggest group will place the value on being able to generate server and client code from an API contract, but this group is fragmented by those who see the code as a source of truth and OpenAPI is purely for generated documentation from your gateway or code annotations. Others will see only the ability to generate mocks, tests, and scan for security vulnerabilities. Some folks with a higher view of the landscape will understand D) All the Above, but believe the value lies in the OpenAPI. All of this is true, except the real value is actually in the alignment OpenAPI brings across the lifecycle, downstream deliverables, and all of the different roles involved in producing and consuming an API.
It is really hard to show people the intangible collective value OpenAPI brings to the table. Depending on who you are and where you are in your own personal journey you will place bets on value being in different places. Few people see the alignment OpenAPI brings—–this takes self awareness, a lot of work, and just the right vantage point in your enterprise and the API landscape. I get why people place the value on documentation, code generation, or on the ability to automate Spectral rules and governance. They see a specific area of API operations and are incentivized to optimize and automate their portion of the puzzle. They aren’t incentivized to see the alignment, communication, or grounding impact of an OpenAPI artifact across all stages of the API lifecycle and across the APIs of many teams. The value of OpenAPI is more than just the specification and the sum of its derivatives—-it is the collective alignment, communication, and collaboration that drips from each property of an OpenAPI.
Getting on the same page in the digital realm is difficult. Seeing the APIs that are powering literally everything we depend on to do business is difficult. OpenAPI has done amazing things when it comes to both of these areas, helping us get not the same as producers and consumers by allowing us to see APIs. Next, I will work on an image to help me see all of this–at the enterprise and industry level. The accumulation of value placed upon an OpenAPI throughout the lifecycle, as well as at the industry and specification level is key here. When I look at any of the numerous API providers I come across who are publishing their OpenAPI to a public GitHub repository, it isn’t the docs, SDKs, or even the OpenAPI that I place value on. It is a robust set of elements and collaboration around OpenAPI, rendering some OpenAPIs more valuable than others, because of the work that is occurring on them by API producers and consumers.
