I learned over a decade ago why API discovery isn’t a solvable problem within the world of technology—the people in charge of the narrative don’t see business, they see technological solutions. Pundits in the API universe often give a blank nod towards APIs.json as part of the API discovery solution, but rarely ever put it to work and adopt as part of their narrative. Why? Because APIs.json provides references to the technical bits they care about, but also provides references to the business bits they do not see or care about-—which nullifies the use case for them. The precision of the technical details like headers, parameters, and semantics are everything, but having to get access to resources, pay for something, and be aware of terms of service are just taken for granted as gravity in our universe and are just part of the reality of an engineers world-—they aren’t things they have to think or care about. I used to think this was just engineers, but now I know it is actually by design.
TypeScript, Smithy, MCP, A2A, JSON Schema, ALPS, RAML, gRPC, and even OpenAPI provide you with much of the technical details you need to care about as an engineer. None of them will actually tell you what you have access to, what it will cost, where to find it, the realiability of a resource, and what change will look like over time. Engineers live in a magical world they have crafted where if you just get all the technical details well defined and documented, and everything else just happens and falls in line. Or at least someone else has to worry about it. I have spent over a decade providing pointers to where to sign-up, login, find pricing, rate limits, SDKs, sandboxes, and the other things engineers do on a regular basis, but seem to feel their technical specifications don’t need to address. And these are just the fundamentals, we aren’t even talking about the other business feedback loops, changes, compliance, and higher level business elements that regularly impact our engineering world.
It is fascinating to me that the API pundit class still feel API discovery is about describing the technical details of an API in a new specification will fix our problems—-opting to live in an XKCD cartoon. It isn’t just that there is another spec, it is that there is another spec with the same technical details shuffled in a new way while also omitting the business details. While I think some folks intentionally disregard the business realities of technological integration and automation because that is someone else’s problem, I think most folks are completely unaware because they only deal in terms of technology. I’ve regularly encountered these folks throughout the years, they are the ones who have elaborate versioning opinions to deal with business changes outside their control, and complex protocols and schema for isolating them from business using their technical wizardry. I’ve always loved watching folks get pedantic about the technical details of API design, development, and authentication, while ignoring discovery, onboarding, access control, usage, and other things like terms of service, privacy, and transparency, because it isn’t something they need to worry about in their day to day.
I am not saying that seeing business will fix much of this. It won’t. I am just saying that in an effort to automate the API realm in the name of artificial intelligence, that folks are making the same mistakes I’ve seen over and over with other work to automate the API realm. If you don’t have reliable access to something, none of the technical details matter. If you can’t afford to access something, none of the technical details matter. If an API is being used to exploit an API consumer, or even exploit an API producer, none of the technical details matter. The challenges with API automation right now are about 15-20% technical, with the rest being a mix of human and business messiness that needs ongoing negotiation between the humans involved. It isn’t something that will be magically unwound in a predictive nature, and will require business stakeholders to get informed and become a part of the process, not further abstract away the technical details in the promise of AI. 95% of the API automation discussions I see happening right now are missing the business and politics of API automation that represents the true challenge to do this reliably, and eneterprises finding themsevels further entrenched in complex technical debt with this round of AI powered “revolution” and “innovation”.
