One area of the API lifecycle that I struggle with helping folks understand the evolution of, is documentation. This fundamental aspect of how we produce and consume APIs has continued expand pretty regularly over the last decade, but is something that isn’t always easy to see and articulate in the moment, and even tougher to get others to properly see and internalize as part of their operations. The most recent evolution in how API documentation is being applied across operations is occurring out of view of some of the folks I talk to because they are beholden to some of the older narratives that have made their way around the API space over the last decade—-stories that seemed sensible in the moment, but are rapidly becoming bottlenecks when it comes to the number of APIs we operate, consume, and orchestrate across our operations.
Swaggerification of API Documentation
The introduction of Swagger was simultaneously one of the more forward moving things in the world of API documentation, while also being something that holds many API Providers back when it comes to their documentation keeping up with operations. I hear a number of folks tell me that they wish Postman documentation could be interactive like Swagger UI, without ever considering the collection that powers API documentation, how you get API documentation by default, as as the portable, executable, and shareable nature of a Postman collection. I don’t fault folks for wherever they may be in their API journey, and I am always eager to find ways to help them see what is around them, so I am fascinated by the staying power that a singe interactive API documentation published to a single API portal can have. My goal is to just help folks see the interactive nature of a collection when used with a runner, monitor, or as part of a pipeline, and the flexibility of sharing your collection (with built-in docs) to any public or private workspace, making available in search, instead of just publishing to a single developer portal. There are a lot more possibilities for engagement with consumers in an interactive way with where documentation has gone on the Postman platform.
The API Documentation Universe Expanding
Like almost every other area of the API lifecycle, the world of API documentation keeps expanding. In 2012, your API documentation came with the API management solution you had adopted. It was very liberating when Swagger UI emerged to help free us, only to be adopted by API management providers and get baked back into our portals. Then we started seeing further expansion on the open source side of documentation with Redoc, and on the commercial side with ReadMe and Redocly. This expansion continues as the number of APIs we depend on continues to grow exponentially, as well as the velocity at which new versions of these API emerge, and then go away. Rapidly expanding and contracting, putting great straight on centralized API portals when it comes to ensuring APIs documentation is always robust, accurate, and up to date. As the pace of expansion continues to grow, even when API documentation is supported by an OpenAPI source truth, enterprise organizations are having trouble keeping pace when it comes to documenting API sprawl, as well as the expansion in how API documentation is being created, deployed, maintained, and evolved.
More Than Just Reference API Documentation
When it comes to API documentation, it is customary to provide documentation for 100% of the available paths, providing a complete set of reference API documentation. Something that can be overwhelming for consumers who are looking for a specific API, or a specific set of APIs that accomplish whatever they are looking to do. With Postman you get documentation by default when you create or generation a collection, making for the perfect medium when it comes to producing documentation that services a variety of purposes across the API lifecycle—-here is a sampling of what we are seeing across the Postman community.
- Reference Documentation – A complete list of available API paths for any API, reflecting what we see when it comes to most API documentation out there.
- Onboarding Documentation – A specific set of the most common API paths that new API consumers will need when it comes to putting an API to work.
- Workflow Documentation – Taking a set of APIs that accomplish a specific business use case and organizing them in the proper order, complete with documentation.
- Testing Documentation – Ensuring that contract, performance, integration, and other types of tests are also fully documented, explaining what they accomplish.
- Mock Documentation – Providing documentation for a mock server that accomplishes a specific business purpose, ensuring the use case is well defined.
- Governance Documentation – Documenting the design, and other types of governance that is being applied across many APIs, using a common set of patterns.
With all of these ways we can document our APIs, it can be a little difficult to stick with the old traditional approach of making documentation available via a single developer portal. Something that applies pressure for the world of API documentation to continue expanding, allowing us to make API documentation available in very different ways, while still making sure we can find what we need. As the number of APIs and microservices increases, and the changes made to these APIs increases, we are finding ourselves more dependent on automation to help us discover, run, monitor, and build documentation–changing where documentation exists, and is made available to team members and consumers.
- Workspaces – Documentation available where an API is being produced or consumed.
- Network – Documentation available via public and private network for consumers to find.
- Search – Ensuring that documentation is always indexable by default for discovery via search.
- Button – Embedding documentation within blog posts, wikis, support documents, and other pages.
- Fork – Forking documentation so it can be used locally, but also receive updates, and make changes.
- URL – Quickly access documentation for any API using a simple URL, quickly consuming anywhere.
- Client – This is where documentation becomes interactive, but it doesn’t stop there and becomes executable.
What I like about this expansion in how API documentation is made available is that it doesn’t just expand documentation, it evolves the notion of what a portal is, changing where and how we find APIs, and how we onboard and put them to work. This approach doesn’t just change where documentation exists, and how we put it to work, it is something that can keep pace with the velocity that exists across operations today, allowing us to find APIs where we need them, and automate the delivery of API documentation so it can constantly be evolved upon based upon the reality of API operations.
The Latest Evolution of API Documentation
I have been intimately studying API documentation for over a decade and it is tough for me to see how things are changing. It is difficult to see the API universe as it expands, especially with the latest wave of expansion being a very private, within the enterprise event. I didn’t have the view of the landscape I needed until I started seeing things through the Postman API platform lens. It is easy to miss the automation of API documentation amidst an OpenAPI driven lifecycle, and the documenting of micro services using collections that are never mean to be mature enough to be published to a catalog, let alone made available publicly. This blog post is meant to help me pause for a moment and take a snapshot of what I am seeing, something that will allow me to build on while I scratch at other things like how examples are provided, mock servers made available, client code is generated, environments are applied, and other expanding parts of how API document is crafted, published, applied, and used to move API operations forward. Eventually I’ll get a little more articulate in how I tell stories about how APIs are being documented, and talk about the influence these approaches have over other areas of the API lifecycle.
This article originally appeared here.
