REST api versioning (only version the representation, not the resource itself)

Question

I had a look at Best practices for API versioning?, but am not quite convinced of the answer, so I am question the versioning part again with a more specific example. I am h

Answer 1

I agree that you don't want to see versions in the URIs of the resources presented in your API. That makes them not "cool". Also agree that the it is representations that are most likely to change.

However it does then raise the question of what happens when you change the contents of a particular representation. For instance if your original JSON representation of a frobnitz is

{"x": "bam", "y": "hello"}

and you want to add a "z" field you may feel that the client should have some awareness that we're now on version 2 of some kind of data scheme.

I'm not sure about that. I think you've got a few options:

• Make your clients flexible in the face a gently changing representations. In the above example we're still generating a JSON dictionary.
• If you must, put a version in the representation itself (a version field in this example). By doing so you're effectively declaring a sub-representation within the JSON content-type. I reckon that's pretty limiting though.
• Use your own MIME types and version them: application/x-my-special-json1.0, application/x-my-special-json1.1. This allows you to version your representations independently of each other. Again, with this one you are making a significant demand on your clients to know what's going on.

In general I think you want to optimize your API and your representations for clients that you haven't invented yourself; ones that other people will create upon discovering your resources. I believe this is useful even in the case when you are making something that is private because it builds in a useful design constraint that will help make your system more robust.