Versioning API endpoints

[speier]

Is there any advice on how to implement versioning?

For example:

api.example.com/v1/magazines.json
api.example.com/v2/magazines.json

[geek]

That is one option, another is to use an accept header like how github does their versioning. See http://developer.github.com/v3/media/

Where the Accept header is in the form:
application/vnd.github[.version].param[+json]

If you want the version to be part of the path then you can include it within the route path property.

server.route({ path: { '/v1/magazines' }

[hueniverse]

hapi doesn't have an opinion on versions atm. We're looking into supporting Accept header for content negotiation which is cleaner than using /v1 in the path. In general, my personal view is that there should be one API. You use the same paths as long as they are backwards compatible, you use Accept header to change the response payload and content-type to change the request payload. And mint new paths for non-compatible changes. I would never do /v1 /v2 but that's just me.

Either way, we will look into supporting these patterns in hapi soon. but probably post 1.0.

[speier]

Thanks for your thoughts. The Accept header idea sounds good.
Also supporting these patterns in hapi would be great. Keep up the good work guys.

[hueniverse]

Moved to backlog.

[hueniverse]

The best source of alternatives: http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown

[hueniverse]

Duplicate of #252

[lock]

This thread has been automatically locked due to inactivity. Please open a new issue for related bugs or questions following the new issue template instructions.