I hit a lot of “How to Draw An Owl” issues while profiling API operations for interesting APIs. These are often things that developers take for granted and just assume people will know about how to put an API to work. One challenge I came across today, which I have encountered before, was how do you articulate that an API is open source and will need implementing. Meaning, when I publish an OpenAPI for Twilio or Stripe, there are explicit sandbox or production server URLs that I can put in the OpenAPI server object. But, when I am profiling an open-source solution as I did with the OpenAPI Policy Agent (OPA) API, there is no sandbox or production URL to put into the OpenAPI server object. So, how do I articulate in a machine-readable way that you will have to deploy the API before the OpenAPI and collections are usable.
The OpenAPI Policy Agent (OPA) API is relative to how and where you are running OPA, and then once again relative to how you will be consuming, integrating, and automating this. OPA can run in a variety of places, and for this discussion, we are only talking about using HTTP. If someone forks my repository for OpenAPI Policy Agent (OPA), where do we point the OpenAPI URL or set the Postman or Bruno environments base URL? Going from discovering OPA to consuming, integrating, and automating with OPA becomes quite a “How to Draw an Owl” situation. This challenge isn’t unique to just OPA, and something I encounter with Kubernetes, Docker, or any open source piece of infrastructure that has an HTTP API. Ideally, an open-source solution comes with a default install of localhost or 127.0.0.1 and a port, and you begin there, but this won’t always be the case. I am considering adding some sort of property to APIs.json to articulate the type of access for each individual API, but maybe some sort of installation or setup property type that provides more detailed instructions on how to put an open-source API to use.
I won’t worry about this situation too much right now. I have a bunch of other open-source APIs I want to profile before I make a decision on how to articulate whether an API is open-source and whether or not it has an instance. I want to better understand the common approaches that open-source tooling makers take when it comes to enabling installation and setup, and maybe I’ll learn some new approaches. I’ve seen some open-source solutions provide one-click installs on AWS, Azure, Heroku, and other cloud infrastructure, as well as different takes on local installation and usage. As more things get automated I think we are going to need a way to articulate installation and setup, as well as which frameworks and platforms are used as part of this work. I think that folks who don’t spend a lot of time thinking about API discovery, onboarding, and integration make a lot of assumptions here, when in reality there is a lot more work and steps involved than one might think. I know folks are expecting AI to just magically figure this out for us, but I am in the camp that we are going to have to be explicit about every single step, while also doing the work to standardize across different APIs to help reduce friction and automate the production and consumption of APIs.
