3 ms·
There are many ways to do it. From an "academic" point of view, the versioning through http accept headers is considered the "best one". I'm usually going wit
by rmoriz 16y ago
There are many ways to do it.
From an "academic" point of view, the versioning through http accept headers is considered the "best one".
I'm usually going with a path prefix as nearly everyone else does.
As you probably have a lot of API users that don't know and care about http accept headers (and their connection libraries usually don't either), it might be a lot of PITA to convince them doing it right.
So imho you can use the "academic" solution and hire some API Support stuff, teaching each customer the benefits and ways to access versioned resources — or just use the most obvious de-facto standard like /v1/posts/<id>.
That's why I use this compromise.
In Addition, the http accept header versioning allows you to version on each resource independently. This might be a good thing but usually the whole API changes and not only one resource (change as in incompatible change, not an addition of some attributes)
- reynolds 16y agoI can't recall a single API I've seen or used that took the academic approach of using HTTP Accept headers. All of the major REST APIs I've seen have used API key X-* headers and most of them use versioned URIs. It seems there are two REST camps: academics and those who actually write real-world APIs.
- technoweenie 16y agohttp://api.tenderapp.com http://api.tenderapp.com. Course, I didn't work on it long enough to need another version :) I think I messed up by using a single version for the whole API. I think it makes more sense to have a versioned mime type for each resource (if that's how you choose to roll).
- technoweenie 16y agoI think it depends on the change. If it's a major change, I'd change the URL and/or host. If I'm removing/renaming a field or otherwise changing the structure dramatically, then I think a custom mime type is appropriate. If I'm just adding a field (in the case of a JSON/XML object), then I probably wouldn't bother doing anything.