API Providers Should Maintain Their Own API Definitions
23 Dec 2019
I am working my way through 2K+ API providers, refreshing my view of the API landscape, and the data I use to tune into the API economy. As I refresh the profile of each API provider, one of the main things I’m doing is looking for an OpenAPI or Postman collection. While the profiling of their API operations using APIs.json is critical, having a machine readable definition for each API is kind of the most important part of this process. Having an OpenAPI or Postman collection gives me a machine readable list of the value that each API delivers, and allows me (and others) to more easily integrate an API into other applications and systems. Sadly, not every API provider understands the need, or is able to invest the resources to produce an API definition.
While profiling an API provider the most ideal situation I can come across is when an OpenAPI already exists in service of API documentation, or the API provider just gets the struggle of their API consumers and they have a Postman collection already published. Ideally, the OpenAPI is publicly available and I don’t have dig it out from behind the documentation, or they have the Run in Postman button clearly published on their website. In the best situations, API providers have their OpenAPI and / or their Postman collections published to GitHub, and are actively maintaining their API definitions using Git, which allows other API consumers and API service providers to depend on an authoritative source of truth when it comes to API definitions for each API they use. I wish every API provider would maintain their own API definitions in this way, sadly very few do.
The majority APIs I come across do not have documentation driven by OpenAPI and do not have Postman collections. When I encounter one of these API providers I spend usually about 60 seconds googling for Swagger, OpenAPI, and Postman + their name in hopes I will find some community generated specs. If I come up empty I will email the API provider asking them if they have an OpenAPI or Postman collection. The responses I get range from silence to not knowing what either of these API definitions formats are. From there, I try to gauge the value and complexity of the API and whether or not it would be worth it for me to create a Postman collection, and autogenerate an OpenAPI from that. If the documentation is standardized I can also scrape and generate a Postman from the HTML, but it all comes down to the value of the API and if it is worth my time. The quickest way for me to create a valuable API definition is within Postman where I get to actually make an API call to each API path, and see the response from each resource.
I’d prefer for API providers to invest the resources into creating their own API definitions. It is their resources and they should own the work. However, not all of them understand the importance of their being a machine readable API definition. My goal is to convince them of the value of having an API definition beyond just documentation, and help them see that they’ll see more integrations with iPaaS and other service providers if there is a ready to go, certified, Postman collection for their API available in the Postman API network. If there is a complete Postman collection I can add an API to my API Evangelist network within minutes, and other service providers I know can do the same. The challenge is that most API providers to not see this layer of the API economy and often need to be convinced that API definitions aren’t just about documentation. It is a lot of work to reach out to each provider and engage with them, but I think it is worth it. At some point we are going to reach a tipping point in the number of API provider who understand having an OpenAPI and Postman collection is the default mode of operating, and then the word will be out and I won’t have to do as much work.
All API providers should maintain their own API definitions. They should publish both an OpenAPI and Postman collection to a common location, preferably in a GitHub repository for easy integration into CI/CD workflows. However, this doesn’t mean that there is not value in the community creating API definitions, and publishing what I consider to be API fan fiction. I find that sometimes the workflow Postman collections created by the community are actually of more valuable than the OpenAPI or Postman collections that comes out of the API providers efforts. While the API providers API definitions may be more authoritative and complete, I find that API consumers usage of an API can possess more creativity than the provider behind the API. Are you an API provider? Do you have an OpenAPI or Postman collection for our API? Are you on my list? If so, you’ll be hearing from me over the holidays, because I am checking my list twice, and making a determination of who is naughty and who is nice when it comes to providing API definitions for their API consumers.