API Spec: where should it be?

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 RapidAPI framework.

If you use gRPC, you must to write a “.proto” file at least.

In any case, where do you put that API stuff?

In many cases the answer is: in the server side.

But the question is: Is it the best place?

Short answer: Not (not for me).

The API Spec is the most important contract in the project.

In many projects, it’s even the first deliverable item.

With the API spec done, the server team and the front end team can start to work.

The frontend team can use tools to create stubs and mocks using the API Spec.

By the other hand, you can have several server implementations, and each one can implement the same or versioned API spec.

The solution

To keep the API in a separate repository while it’s easy to manage and work with it, I use the following simple solution: API as git submodule.

The schema is the following:

  • The API repository.
  • A Server repository with the API repository as submodule under “api" folder.
  • A Client repository with the API repository as submodule under “api" folder.

For example, if we need to add the API repository in a new server repository, we do something similar to:

git submodule add <api-repo-url>

If we have already the API spec as submodule, once you have clone the code, you need to get the latest version

git submodule init
git submodule update

And voilá! You use the API but the API has its own “home”.


The API spec very important and it need a dedicated repository. It’s bad to have it mixed with the server implementation code.

And of course, the API can iterate in isolated way from client and server code.

The API is the star of your project, put it where it deserves :)

CTO @ Digitalilusion.com & DigitalSecured.net Beyond-Full-stack developer #go #python #kubernetes

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store