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.

  • Changing your URI from v1 to v2 is a breaking change. It's essentially a different endpoint, regardless of what happens under the hood. May 5, 2021 at 20:49
  • Yeah but removing one field from request body is also breaking change, isn't it? People are going to get 403 because of this change. Can you give me an example reason of major change? Examples will help me to understand
    – Berkin
    May 5, 2021 at 20:50
  • My impression of V numbers in URI's is that they're typically used when you create a whole new API, not to manage ordinary, breaking API changes. If you change the number of parameters, the clients are going to get a 301 or 403 anyway. May 5, 2021 at 20:53
  • 3
    And for what it's worth, SEMVER is generally used to track software updates, not REST API changes. May 5, 2021 at 20:55
  • That said, have a look here. May 5, 2021 at 20:57

1 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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.