search

hyperoslo / api-playbook

A place to define the conventions we use to build APIs
4 stars 1 forks source link

Add proposal for api versioning #4

Closed fespinoza closed 6 years ago

fespinoza commented 9 years ago

i propose to use the Accept header in order to clean URLs of the resources, and because my main approach on the design of the API is to use the header to communicate data, because that is why HTTP headers were built for

and we will use them for several applications, as localization, caching, authentication, etc.

jgorset commented 9 years ago

I like headers, too, but mostly just because that's what headers are for. I guess it makes it harder to share the endpoints because you won't be able to do it with just an URL, but I'm okay with that (you'll probably need to authenticate anyway, and you definitely don't want that part in the URL). So that's :+1: from me.

jgorset commented 9 years ago

We have some missing capitalizations and punctuations in this pull request though, so I'm fixing those; I think beautifully written English in our playbooks is as important as beautifully written code in our applications. :-)

jgorset commented 9 years ago

What do you think about this, @hyperoslo/ruby?

JozoSalt commented 9 years ago

I kinda like using a custom-header for versioning API-Version

And there is this when using Accept header in Rails (from versionist gem):

Accept Header Gotcha

Please note: when your routes do not include an explicit format in the URL (i.e. match 'foos (:format)' => foos#index), Rails inspects the Accept header to determine the requested format. Since an Accept header can have multiple values, Rails uses the first one present to determine the format. If your custom version header happens to be the first value in the Accept header, Rails would incorrectly try to interpret it as the format.

fespinoza commented 6 years ago

close because of inactivity