Title says it all. Should I increment my API version if I add, say, an image property to each instance of my JSON-represented 'Restaurant' resource? or should API versioning change only when implementation changes?

  • 1
    Does a consumer of your API care about the implementation? Or do they care about the interface?
    – jonrsharpe
    Jan 14, 2017 at 20:07
  • 3
    You're describing a schema change, not a data change.
    – MetaFight
    Jan 14, 2017 at 20:37

3 Answers 3


Let us say you have released version 5.2.11.

Now you add images to your json output and continue to call it version 5.2.11.

Would you really like to have your customers asking when the images are going to be included, you are still running 5.2.11 nothing have changed. Trust me they never check.

Isn't much easier to tell your customers: we now use version 5.2.12, you do not have to change anything, but if you like there are added images.


The principle is quite opposite. You increment version on any tiny change of the API unless there is very serious reason not to do so.

What are your reasons? How you are going to document such API? How you are going to write what version of API was used to reproduce a bug? API users won't be happy to hear that "now we do not guarantee that servers with the same API version return the same answers".

Stay safe and increment.


API version needs to change if any of the clients has problems with the changes. So find out if your clients have problems with an image property being added.

  • I would personally also increase the version if I add features to an API. No clients may have problems with those changes, at least initially. But they may afterwards, once they start to use them. So I think your description is either wrong or incomplete. Jan 14, 2017 at 23:45

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.