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
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.
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 :)