Allow use of version in Accept Header

[pixelhandler]

Allow versioning of an API endpoint via Accept header like so:

application/vnd.api+json;version=1

Perhaps allow for configuration to allow the check to use a loose match of "begins with" for the accept header.

The JSON API spec concluded without any media type parameters…

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.

But that limits a good strategy for versioning an API endpoint via Accept Header. The Accept header generally allows media type parameters, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

Motivations:

• https://github.com/EDMC/api-versions#versions-are-specified-by-header-not-by-url
• http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http#i_want_my_api_to_be_versioned
• https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/
• https://blog.pivotal.io/pivotal-labs/labs/api-versioning

Related Comment on the spec - json-api/json-api#406 (comment)

It would be great if ActsAsResourceController#valid_accept_media_type? could accept "application/vnd.api+json;version=1"

For example, I use https://github.com/EDMC/api-versions

The workaround is to re-define the method like so:

def valid_accept_media_type?
  media_types = media_types_for('Accept')

  media_types.blank? ||
    media_types.any? do |media_type|
      (media_type.start_with?(JSONAPI::MEDIA_TYPE) || media_type.start_with?(ALL_MEDIA_TYPES))
    end
end

[pixelhandler]

@lgebhardt re: https://github.com/cerebris/jsonapi-resources/pull/869#issuecomment-253284703

I'm approaching the versioning from the standpoint that a server will support multiple versions simultaneously. In JR this is easily done with the URI and name-spaced resources. It would not be an easy retrofit to allow version switching based on the media type. However I can see using the media type version as a version check. Are you designing your server to speak multiple versions, or using the version to indicate the current version that the server is speaking? Hope that question makes sense.

On two projects I use two different solutions… one uses only the URI; the other uses only the Accept Header. Both have their use cases. The one with the URI including a version in the path is private, the one with the Accept header is public (example: http://mwwondemand.github.io/#orders)

On both cases any endpoint can have multiple versions for the entitiy, e.g. v1 and v2. And consumers need to specify that version.

With the API versions gem the routes check for the version in the accept header; JR does not need to handle versioning. We had to use the workaround above to allow the Accept header check to work.

In both cases each endpoint has a route + namespace e.g. api/v1 Api::V1 to handle what version of the resource to work with.

[lgebhardt]

@pixelhandler Thanks for clarifying. That all makes sense.

[krainboltgreene]

Honestly just let us configure the accept/content-type. Currently I have to overwrite the JSONAPI::MEDIA_TYPE.

[dgeb]

@pixelhandler Given the changes in #869, I think that valid_accept_media_type? is now compliant with the spec. If you want to loosen this check, you'll need to override this method or verify_accept_header in your controller.

Currently I have to overwrite the JSONAPI::MEDIA_TYPE.

@krainboltgreene That seems reasonable to me if you want to use a completely custom media type (say, application/vnd.myorg+json) in requests and responses as if it's application/vnd.api+json. Let us know in a new issue if you have a suggestion to make this cleaner.

[krainboltgreene]

Yeah I tried this and ended up having to change three other methods and two
other configurations and it still didn't work.

On Oct 26, 2016 8:25 AM, "Dan Gebhardt" notifications@github.com wrote:

Closed #874 https://github.com/cerebris/jsonapi-resources/issues/874.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/cerebris/jsonapi-resources/issues/874#event-837229850,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAUb2ZFNguTUvPf3YDgz2jNPab_gUUvAks5q33CwgaJpZM4KU-7b
.

[dgeb]

@krainboltgreene Ah, I misunderstood and thought you were able to get something working with a simple override. Can you describe your use case in a new issue? Are you trying to support something like application/vnd.myorg+json?