OpenAPI cures the symptoms, not the disease

At Apiary.io, we were promising to solve one immense pain for developers: API documentation. The pain was so big that developers would rather learn API Blueprint or Swagger (now OpenAPI) instead of writing documentation by themselves. It has turned out developers need more than a reference of the endpoints to build a successful API, something we could never deliver generating documentation from a specification.

We failed the mission because we were not fixing the root cause: APIs need engineers to integrate APIs. And now, we are still just serving painkillers with OpenAPI to cover up the symptoms.

Yes, having a reference is better than an undocumented API. Everywhere where API client self-service matters, additional documentation is needed. But no developer wants to write it. And if someone does, a new extensive problem arrives: How do you keep the documentation in sync with reality?

Tools

So we have built tools. We built testing tools like Dredd to test API description and its API implementation. Mock services for quick prototyping. Interactive documentation for developers to play with the API because the documentation itself is not enough to explain the API clearly. We incorporate all these tools in the pinnacle of "humans connecting the software" – the developer portals.

And we have built more tools. Because we have not dealt with the core of the problem, we created even more pain points. We looked at our designs and said: Oh, you can’t publish the API because it has a poor design! All the company APIs must look alike because it is easier for human developers to comprehend and connect. So the API guidelines and tools like Spectral were born.

Painkillers, not the solution

We keep covering up the symptoms, but we create more problems in the process. I have contributed to all these concepts both as the author of API Blueprint and later as a consultant. And though we left the world in a better place, these tools will not take us much further. What we are doing is not working.

To move ahead, we need to solve the root cause of the problem. We must stop having people writing API documentation so other people can find it on Google (or internal catalogs) only to bake whatever is in the docs to their software. And when they do, they need to eyeball the documentation as long as they want their integration to work. This might work for software libraries but not for distributed systems.

The Cure

So what is the solution? Autonomous APIs. Self-integrating applications. A distributed infrastructure where applications can meet, enter into a contract, and connect based on how they are programmed without knowing each other's implementation details.

Autonomous systems will replace client-facing documentation. They will minimize the time needed for integration, nullify the maintenance, and massively reduce client and server codebases. The API design will be only a matter of performance, not a tool to attract (or not to lose) client developers. Oh, and those annoying API integration tests and invasive integration platforms? They will go away too! We do not need proxy platforms to connect if our application can self-integrate!

Let’s fight the disease!