A rant about APIs

Over the past few weeks, I've integrated with multiple APIs for Vori's onboarding flow, including contract rendering, e-signature collection, invoicing/billing, CRMs, card processors, and gateways. These APIs have their own unique annoyances, but they're especially frustrating given that many have been around for a decade. It's disappointing that developers can't simply copy existing, better APIs and practices to improve their offerings.

I shouldn't need to log in to read API documentation, yet many require this step, disrupting my workflow and forcing me to wait for support responses to access crucial information.

One team acknowledged that gated documentation is not ideal, yet executives continue to push for it. This is especially problematic for agentic development, where providing links to documentation disrupts the flow of building a client and integrating. I'd prefer to share documentation links with agents so they can explore the schema, build a client, and integrate without unnecessary barriers.

The lack of authentication requirements for documentation is a waste of time and resources, and it's disrespectful to developers who have been publishing APIs for over a decade without providing OpenAPI specifications. I'm not asking for a Postman collection; I need an OpenAPI spec to generate a typed client and focus on building my business. Why settle for inferior formats when good ones are available?

Issuing credentials can be necessary, but waiting weeks for IT to generate them is frustrating. Rotate credentials quickly, and don't make me file support tickets for potential security incidents. Self-serve credential issuance is better, but the fact that credentials are tied to the identity of the person who created them creates issues with log association and credential rotation.

I'm considering migrating away from e-sign providers that tie credentials to user identities, as it hinders incident resolution and accountability.

Webhooks are great for building real-time workflows, but I dislike providers that verify webhook endpoints before saving them. Sending a payload to the endpoint and only saving the configuration if the response is successful is an unnecessary hurdle. It's hard to validate without a shared secret, and the provider won't provide one until the endpoint is verified. Writing a support ticket about this issue wasn't helpful, as the team didn't understand the problem, and their response only served to prolong the issue.

Despite the frustrations, progress is being made. Building APIs is better than nothing, even if the developer experience is horrible. I'm thankful for the strides being taken, but we need to do better to avoid wasting time and resources on subpar solutions.