Content Negotiation - Githubissues

restful-api-description-language / RADL

RADL: A description language and tooling for hypermedia-driven RESTful APIs

Apache License 2.0

23 stars 5 forks source link

Content Negotiation #17

Closed jonathanrobie closed 9 years ago

jonathanrobie commented 9 years ago

RADL currently does not specify precedence for content negotiation. Shouldn't this be part of an API description?

RaySinnema commented 9 years ago

If the API only supports a single media type, content negotiation obviously isn't an issue. This is probably true for the majority of APIs.
If the client sends an Accept header, then the server should honor that rather than its own precedence.
If the client doesn't send an Accept header, then the server is free to choose. If the client can handle all of the possibilities, then there is no problem. If it can't, then it seems unwise for it to hope that the server picks something that it can handle. IOW, it really should send an Accept header, which brings us back to the previous case.

So all in all, I don't think this is interesting enough to include in RADL.

gentlewind commented 9 years ago

This is actually a super issue of #14, when there are more than three media types on the server side.

If the client doesn't send an Accept header, then the server is free to choose.

Does it mean the server is free to choose the default media type as well? :)

The media type sequence means that when the server does not violate the content negotiation, which media type it should respond to the client is according to a sequence of the subset of the media types that the server can determine. The default media type is just the 1st one on the sequential subset.

Here is an example.

Assumed the server supports three media types 'application/vnd.acme+json' (default) and 'application/vnd.acme+xml', 'application/vnd.acme.v2+xml'.
The client sends a request with 'Accept' header 'application/vnd.acme2+json,application/*+xml'.
Should the server set an expectation to the client that 'application/vnd.acme+xml' will be served?

The quesiton is should this sequence be documented?

RaySinnema commented 9 years ago

I'm not sure I understand the question. The server is supposed to pick the most-preferred media type from the Accept header. The client is supposed to handle anything it requests in the Accept header. What's there left to document?

gentlewind commented 9 years ago

The question is about when the server can offer multiple media types for the Accept header with the equaling q factor, should it indicate the precedence of these available media types. Maybe I have overlooked at it. This is a corner case in most REST APIs and RADL can just ignore it.

RaySinnema commented 9 years ago

It doesn't matter what the server's preference is. The client indicates in the Accept header all the media types it can handle, so as long as the server returns one of those the client should be good.

jonathanrobie commented 9 years ago

A REST client can see the available media types in the RADL and specify which ones it wants in the Accept header, and the order that the client prefers. If the client specifies a set of media types, it shouldn't care about the precedence the server uses to choose among them. In general, a server should let the client specify which one is preferred.