How is it a bad misuse? It's used to specify the MIME type. Why is it so much of a stretch to also specify which version of the MIME type to use? I personally think this is the cleanest and most unobtrusive way to version an API. I'd rather change that than have to change the URL all the the time. Not to mention that /api/vX/... is just ugly.
I don't understand how changing one or the other of these things is somehow easier, nor does it make sense to try to claim one or the other is "ugly"... seriously? Do you even see these requests? I just don't understand this thought process.
The Accept header specifies the acceptable MIME types for the response. It doesn't specify how the request itself is supposed to be interpreted. Picking between alternate MIME types with the Accept header is still supposed to give you the same content, just in different representations.
The proper solution here is to just define a new header, like X-API-Version (note: the article picked a header API-Version, but since this is a non-standard vendor-specific header it should be prefixed with X-).
If the only difference is the data returned, and not anything to do with how the request is actually interpreted, then I guess it works. But API versioning covers more than just changing the fields in the JSON response.
If the client knows the version to send, they can send a different request format as well and you'll know how to interpret it due to the version header; that header isn't just used for the response, it's an agreement about what the specific message format in both directions is. If he's looking for a version 5 response then parse it as a version 5 request. I don't see the problem? Now your media types and versions of those types can vary and grow without messing with your resource locations which can remain stable. Beyond that you can now version each resource independently rather than forcing the app as a whole to change.
Your problem is you're taking a header that's explicitly intended for selecting among multiple response types, and using it to control how the request itself is processed. That's simply incorrect. That's not what the Accept header is meant to do, and using it that way is confusing.
> that header isn't just used for the response, it's an agreement about what the specific message format in both directions is
No, it's not. The Accept header is strictly about the response.
A lot of the time, "breaking the API" means "breaking the response that comes back", which in turn means that the client doesn't know what to do with the response (can't parse it, missing fields, different schema etc.).
If I change my API so that "POST /widgets" does something different on the backend but returns the same response, then from a client compatibility perspective this isn't a breaking change.
> No, it's not. The Accept header is strictly about the response.
OK, if you want to be that strict about it, then you use both the ContentType and Accept headers to specify what version of the request and response you're making/wanting.
The Content-Type specifies the MIME type of the body content. So even that's not good enough for actually interpreting the URL or URL parameters. Content-Type would only work if all of your APIs go through the same URL and strictly use the body content for the actual request (which would be a pretty awful API).
Fair point; I still say if you're requesting version 5 response then the server can interpret the request as version 5 as well and act accordingly, they're necessarily linked regardless of the Accept header being about the response; it must necessarily imply the request URI version format.
I can see why you're saying that, but I still disagree that this is a valid usage of Accept, and at a minimum it's going to be confusing, because nobody expects the Accept header to affect interpretation of the request.
I'm also not sure why anyone would even want to use Accept for this, given that if you can set Accept, you can also set something like X-API-Version.
It's not only a valid usage of accept, it's simply necessary; you can't possibly process a request for a version of a response without assuming the request contains the necessary information said response requires. If you don't expect the Accept header asking for a specific version to affect the processing of the request, I think you really haven't thought it through as it necessarily must since the output response version must be correlated with the input request. If output version 5 requires a different set of input args, then your code for processing the output will have to assume those args present and thus will have to assume the request was formatted correctly for version 5 otherwise you'll have to throw an error saying the request was formatted incorrectly.
Yes, you could use a custom header, many do, but then you're stepping outside of the HTTP standard, the Accept header is supposed to define the response format, not some custom one you make up, and version is another facet of the response format and must imply the request format matches the required data of the requested output format.
...what? Your comment literally makes no sense to me.
> Yes, you could use a custom header, many do, but then you're stepping outside of the HTTP standard
No you're not. The HTTP standard allows for custom headers, and nothing in the HTTP standard restricts servers from using customer headers to influence how they process the request.
> Accept header is supposed to define the response format
Yes, like application/json. It's not supposed to define the request content, just the format, and it's definitely not supposed to affect the way the request is processed.
> version is another facet of the response format
No it's not. JSON is a response format. XML is a response format. "API version 5" is not a response format.
Look at the mime-type declaration again - its not application/json. It is a representation of a resource in JSON format. The resource is the part thats changed, and interactions with that resource are defined as part of the mime-type.
