Clarify the versioning strategy for APIs

[extesy]

I think it would be useful to standardize the approach to versioning the API. For example, when I want to change the request or response format for some API endpoint, which is backwards incompatible. How should the client tell which API version to use?

There are many different approaches to this: put version in url like /api/1/action or /api/v1/action or in the header, like "Content-Type: application/vnd.company+json.v1" or "X-API-Version: 1".

How about explicitly including the strategy to versioning API in this specification?

[tkellen]

This seems like it falls outside the scope of json-api. Any of those options seem fine,
though!
On Mar 5, 2015 7:55 PM, "Oleg Anashkin" notifications@github.com wrote:

I think it would be useful to standardize the approach to versioning the
API. For example, when I want to change the request or response format for
some API endpoint, which is backwards incompatible. How should the client
tell which API version to use?

There are many different approaches to this: put version in url like
/api/1/action or /api/v1/action or in the header, like "Content-Type:
application/vnd.company+json.v1" or "X-API-Version: 1".

How about explicitly including the strategy to versioning API in this
specification?

—
Reply to this email directly or view it on GitHub
#406.

[extesy]

Why is it outside of the scope? It's quite an important aspect of API design.

[extesy]

By the way, at least one technique (using Content-Type header) conflicts with existing json-api spec which requires using specific "Content-Type: application/vnd.api+json" header value.

[dkubb]

@extesy I have an API where the clients use Accept: application/vnd.api+json; version=1 to select the api version. The version corresponds to the app's versioning scheme, not necessary json-api's version. If I make a backwards incompatible change, like removing or renaming a relationship, I bump the version up. I've been using versioncake to manage negotiating the proper view template based on the version.

Hope that helps.

[hhware]

While it is up to the implementation to decide how to communicate the API version (in URL, headers or elsewhere), would it be reasonable to include a recommendation to use a specific strategy for versioning APIs? IMHO, semantic versioning is a good candidate for this.

[bintoro]

It would seem to make a lot of sense to come up with a common convention for advertising a specific JSON API version. I mean why not? Doesn't have to be decided before 1.0 though.

I have an API where the clients use Accept: application/vnd.api+json; version=1 to select the api version. The version corresponds to the app's versioning scheme, not necessary json-api's version.

@dkubb That doesn't look very safe, since it's not out of the realm of possibility that JSON API might want to use the same parameter in the future.

[extesy]

That doesn't look very safe, since it's not out of the realm of possibility that JSON API might want to use the same parameter in the future

And that's one of the reason why I proposed to have the spec define the strategy. Otherwise, some custom solutions conflict either with existing spec already, or might conflict with some future version. To avoid these conflicts, spec should define the only one "blessed" approach.

[steveklabnik]

I'm for adding a reccomendation, but we don't need this in the actual text. Will post more later.

[ColtonProvias]

It seems like each version of an API should be on its own in its own directory. Thus any changes in format won't affect the previous at all. Then you can have something like this:

/api/1/users returns an XML resource
/api/2/users returns a binary resource from that time when you got drunk and thought this would be best.
/api/3/users returns a JSON-API resource.

The JSON-API base exists in the folder and thus the prefix (/api/3) falls outside of the spec. Essentially JSON-API starts at the resource type in the path and covers everything to the right of it. Everything left of the resource type is your own design. If you want your API to be https://catfacts.io/annoy/some/users, go right ahead.

[extesy]

@ColtonProvias That's just one of the ways to do api versioning, but not the only one. There are even solutions other than path and header, for example see how Stripe is doing it: https://stripe.com/docs/upgrades

[ColtonProvias]

True. Even though it is deprecated, maybe a x- header would do the trick.

X-API-Version: 1

The question still exists of if this should be part of the standard or if it is outside of the spec. Some sites probably have old versioning schemes in place that if we specify a particular scheme, it may conflict. Keeping backwards compatibility then would be a major issue.

[visualasparagus]

Would it be an idea to have either a namespaced version parameter to avoid collisions with the jsaonapi spec? So something like this? Not certain if the dot is allowed as part of a parameter name though.

Accept: application/vnd.api+json;version.com.my.api=1.1

[ceyko]

@visualasparagus A dot is indeed allowable as part of a token as per RFC 2616 §2.2

I'd argue in favor of namespaced versions for the same reason. With the exception of reversing the order:

Accept: application/vnd.api+json; com.example.api.version=1.1

More generally, namespaces SHOULD be used for any media type parameters. Including those used by json-api.

[krainboltgreene]

I needed this information from the jsonapi spec but it's not in the jsonapi spec, is there a reason? I really really like using the key/value store in the Accept header's parameters.

[Art4]

@ceykooo Your solution looks best to me. But than I noted this in the spec:

Clients that include the JSON API media type in their Accept header MUST specify the media type there at least once without any media type parameters.

So I ended up with something like this:

Accept: application/vnd.api+json, application/vnd.api+json; com.example.api.version=1.1