I’m burning my way through profiling, updating, and refreshing the listings for about 2K+ APIs in my directory. As I refresh the profile of each of the APIs in my index I am looking to make sure I have an adequate description of what they do, that they are well tagged, and I always look for an existing OpenAPI or Postman collection. These API definitions are really the most valuable thing I can find for an API provider, telling me about what each providers API delivers, but more importantly it does the same for other consumers, service and tooling providers. API definitions are the menu for each of the APIs I’m showcasing as part of my API research.
As I refresh the profile for each API I re-evaluate how they do their API, not just the technical details of their API, but also the business and on-boarding of their API. If an API providers doesn’t always have an OpenAPI, Postman collection, or other machine readable definition for their APIs, depending on the value of the API and standardization of their API design and documentation, I will craft a simple scrape script to harvest the API definition, and generate the OpenAPI and Postman collection automatically. As I cycle through this process fore each API in my index I’m reminded of just how different APIs can be, even if they are just RESTful or web APIs. Demonstrating that there are many interpretations of what an API should be, both technically, and from a business perspective.
Some APIS have many different paths, representing a wide variety of resources and capabilities. Some APIs have very few paths, and heavily rely on query parameters to work the magic when it comes to applying an API. Others invest heavily in enumerators and the values of query parameters to extract what you need from each API—often times forgetting to tell you what these values should or could be. Some of the time an API provider will share documentation with you outlining most of what an API will do, but more often than not I come across APIs with entire blindspots of functionality, leaving me fumbling around trying to piece together what is possible with an API, making it difficult to ever consider a profile of an API, and the resulting OpenAPI or Postman collection truly complete—I just do not fully ever know, unless an API provider actually owns and updates the API definition themselves.
Beyond just the many differences in API design there are many differences between the business of an API. How you find the API, learn about it, on-boarding with it, pay for it, get support, and the other required elements before an API provider and consumer can find common ground. I regularly end my profiling of an API during the frustrating signup and on-boarding process. If I can justify the value of an API, I have less than 10 minutes to on-board and be seeing value, otherwise I’m just walking away. APIs that possess common building blocks as part of their API portal, and employ proven API management solutions for the sign-up, on-boarding, and overall developer engagement are easier to use, and possess less friction when it comes to getting started. All the steps are familiar for me, and just make sense—I do not have to work overtime understanding how I will get access to an API. It just works.
After a decade of navigating the differences between APIs I am unsure how to convince API providers to standardize on how they deliver their portal, documentation, on-boarding, and design of their APIs. It doesn’t mean I will stop encouraging them to do so, and help define standard definitions, services, and tooling that help them along the way. While we should keeping putting information out there regarding how to best design your API, then publish and make available in a standardized way, I’m thinking we are going to need other ways to demonstrate to folks the differences in the APIs they are delivering, and how they compare to other APIs within their own company or industry. I feel like people don’t have a sufficient enough view of the landscape to see their own position within it, and haven’t spent much time using other APIs and developing a shared API vocabulary with their community. I think differences in APIs can be good, because there are many different ways to tackle integration, but I fear that the many differences I’m seeing are for all the wrong reasons.
