How to write a service API correctly?

Question

API

Hello, I need to write an API for the service.

The task seems to be clear and the question has already been asked here many times, but ... everything is more complicated here. Actually now I will share my opinion and call for a discussion thereof.

What do you want:

1. Versioning
2. No code duplication

Versioning

It's nice when the service has an API, but the trouble is when it prepares a new version, releases it and all the old clients probably stop working. This is what versioning is for. And support for older versions.

I am not a supporter of the REST architecture (let's not talk about it), so we will pass the version and data type to the URL, for example service.com/api/v3/json/ . I also want to limit myself to
only POST requests indicating the method being called and related parameters. At this point in my life, I find this to be the most convenient way for third-party developers to work with.

No code duplication

I thought it would be nice if the service inside would work with the same models as the API. Therefore, if the API is versioned, then with the new version it will be necessary, for example, to simply copy the models folder, thereby creating a new version, and edit only this folder so as not to affect other versions at all, so that third-party developers can sleep peacefully. The project inside should always work with the latest version of the models. The controller for the API should be only one and preferably for all versions and simply redirect the request to the desired model from the request (or according to the method map).

I thought so - if you still do any processing in controllers, then you still won’t save yourself from modifying models, and when editing models, changes will affect all versions, so the models will still need to be copied or invent multi-versioned storage - it doesn’t matter , the main thing is that the changes will be in two places.

I invite you to have a good discussion about this decision.

Answer 1

Did something like this recently. I got general models, processing in controllers. And by the way, already when I did it, I tried to imagine the situation that it would be necessary to make another version - it didn’t work out. All hypothetical changes fit into the current version, taking into account backward compatibility, but left the possibility of versioning.
Before writing, I studied quite a lot of literature, blogs and presentations, I even started writing an article on Habré, but so far laziness has won. The most useful thing I've read is REST API Design Rulebook , I recommend it.

Answer 2

KeepYourMind Yes, it's just clearer in the url

Answer 3

jacobian.org/writing/rest-worst-practices/ good article

Answer 4

Models cannot be duplicated by definition. Have you changed the data structure in the storage (for example, in the database), and you are working with the new table using the old code?
There is only one way out - to make the API from the simplest and thinnest layer of controllers as possible, and edit them when the models change. You might consider generating the API automatically, for example based on the description (CUI function name - Involved models - Transmitted fields and their mapping), if possible. From the same description, in a particularly successful scenario, it is possible to generate documentation for the API.