API Spec: where should it be?

JM Robles
3 min readDec 13, 2020

TL;DR: The API definition and documentation must be in a separate repository.


In the desktop or CLI apps era, you probably only had one folder where you would put all your code.

When the CVS arrived, you put that folder in version control.

With the Internet explosion, the develop paradigm turns into a client/server pattern.

In this case, it’s normal to split the project into two separate repositories: one for the backend/server and another for the frontend/client. Not?

There are several reasons to do that split.

For me, the most important is that the software cycle of each component is independent. Other reason is that you can have several clients or frontends (think in the one thousand Twitter clients, for example).

But as you know, to communicate the client with the server you need, normally, an API.

The answer to the question about where to put the API stuff is what we’ll try to resolve here.

The API Spec

In a good project, your API must be documented. Probably you use Swagger or OpenAPI Spec to do it.

Sometimes you prefer to use a auto-doc generator like as the included with…



JM Robles

AIOps @ Montevive.ai / Backend / Platform engineer #llm #rag #llamaindex #langchain #go #python #kubernetes #terraform #devops