Add proposal for api versioning

[fespinoza]

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.

[fespinoza]

note the definition of a vendor content type, depending on the app vnd.super-app+json

[richardtop]

What do you think about these kind of versioning?
GET hyper.super-app.no/api/v1/spaceships

It is also cleaner, but there is a benefit in seeing clearly, what version you are using.
When updating the apps to newer API, only baseURL change would be required to start development with new version.

[fespinoza]

i like that approach as well

the reason I am proposing the header version, it's that we will be using headers for many purposes already

and other intelligent people are using headers as well

there is a discussion in that repo as well, but i want to read a little further to understand the choices

but mainly, the purpose of this PR is to evaluate options

[jgorset]

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 👍 from me.

[jgorset]

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]

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

[JozoSalt]

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]

close because of inactivity