How To Use Semver In REST API Versioning

Question

I am trying to understand one thing of using semver in rest apis. Semver says that

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented. https://semver.org/#spec-item-8

In software world requirements change day by day rapidly. Sometimes you will find yourself writing backward incompatible development to fulfill that request. According to semver you have to increase major version number if you are not in 0.Y.Z version. But wouldn't that you to bump into high numbers rapidly. I will give you a real world example.

Lets assume you are in v1 right now. Published 3 endpoints. These endpoints work properly for a while. Also there are validations to check request body for each endpoint.

POST     /v1/users
PUT      /v1/users/{userId}
DELETE   /v1/users/{userId}

Then a requirement came up. Due to GDPR restrictions you have to remove single field from request body. Here is the problem.

When you removed a single field from request, you also removed it from validations. Thus when I call that endpoint I am going to have;

403 Bad Request

So I need to change my side too.

---

In this situation, should responsible developer increase their version number to 2?

If so, won't you end up having higher major versions soon?

What about DELETE method? It doesn't have request body. Should also its version number upgraded to 2? Like

DELETE /v2/users/{userId}

What is going to happen v1 versions. Should I return 301 Moved Permanently with Location header?

For example Spotify's API. They are still in v1 for years. They must have made backward incompatible changes before.

Answer 1

Requirements to remove fields from an API (regardless if it is a REST API, a classic library, or some other kind of component) can usually be resolved by removing those fields semantically, not syntactically. So the body of a message may still contain the field, but

• the content of that field can be always left empty by the sender

• and always be ignored by the receiver (though syntactically validated).

If an API has collected too much technical debt over some time this way, then one may consider to make a new cleaned-up API and increase the major version number. These things usually happen in time ranges of years, not days or weeks, to give people enough time to adapt their depending code.