News for hackers. Stuff that matters.
Re:How to Version an API by eridius on Thursday June 08, 2017 @04:16PM (#14516887)
> Header versioning in the wild is primarily done via a customized Accept HTTP header.

Is this true? I haven't looked at very many web APIs, but I haven't run across anyone using Accept in this way, and it strikes me as a pretty bad mis-use of that header.

Re:How to Version an API by Dirlewanger on Thursday June 08, 2017 @04:57PM (#14517141)
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.
Re:How to Version an API by saurik on Thursday June 08, 2017 @07:08PM (#14517890)
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.
Re:How to Version an API by eridius on Thursday June 08, 2017 @06:50PM (#14517773)
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-).

Re:How to Version an API by gnaritas on Thursday June 08, 2017 @07:02PM (#14517866)
A different version is just a different representation of the same resource, the Accept header is the correct way to do it.
Re:How to Version an API by eridius on Thursday June 08, 2017 @08:44PM (#14518393)
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.
Re:How to Version an API by gnaritas on Friday June 09, 2017 @12:40AM (#14519210)
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.
Re:How to Version an API by eridius on Friday June 09, 2017 @01:02AM (#14519275)
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.

Re:How to Version an API by growse on Friday June 09, 2017 @06:58AM (#14520525)
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.

Re:How to Version an API by pvorb on Friday June 09, 2017 @03:03AM (#14519632)
Yep, you should also send a Content-Type if your request has a body.
Re:How to Version an API by gnaritas on Friday June 09, 2017 @10:58AM (#14521835)
> 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.

Re:How to Version an API by eridius on Friday June 09, 2017 @02:44PM (#14523463)
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).
Re:How to Version an API by gnaritas on Friday June 09, 2017 @02:52PM (#14523525)
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.
Re:How to Version an API by eridius on Friday June 09, 2017 @02:57PM (#14523555)
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.

Re:How to Version an API by gnaritas on Friday June 09, 2017 @06:46PM (#14525143)
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.

Re:How to Version an API by eridius on Friday June 09, 2017 @08:01PM (#14525456)
...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.

Re:How to Version an API by jalfresi on Friday June 09, 2017 @04:00AM (#14519881)
The mime-type has changed. How you interpret the mime-type has changed.
Re:How to Version an API by solatic on Friday June 09, 2017 @02:07AM (#14519460)
Because the version of the API is not the version of the MIME type. It's not like JSON itself came out with version 2 of the JSON specification.
Re:How to Version an API by jalfresi on Friday June 09, 2017 @03:58AM (#14519873)
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.
Re:How to Version an API by greencurry43 on Thursday June 08, 2017 @04:30PM (#14516962)
I've seen some use a versioned media typed like GitHub [0] or add a version parameter like "vnd.example-com.foo+json; version=1.0" [1]. People may use this version for the entire API or for versions of that specific resource as well.

[0] https://developer.github.com/v3/media/ [1] http://blog.steveklabnik.com/posts/2011-07-03-nobody-underst...