Search code examples
httpcontent-negotiation

Content negotiation and extended media types


Some media types are extensions of other media types. Such media types often use + in their name to signal this. For example, application/atom+xml extends generic xml and application/hal+json extends generic json.

My question is: what should be done if a client requests the generic media type and the server wants to respond with one of the extended media types? For example, if a request has the header Accept: application/json and the server wants to respond with application/hal+json, should the server...

  1. ...deliver a plain-jane JSON with Content-type: application/json, i.e. don't include _links or _embeddeds? That's what the client asked for and that's what it gets. If you wants HAL, ask for it.

  2. ...deliver the HAL representation with Content-type: application/json? HAL, after all IS json and that's what the client asked for. The client is happy and can ignore the bits it doesn't understand.

  3. ...deliver the HAL representation with Content-type: application/hal+json? Like 2., the client gets what it wants and can ignore the bits it doesn't understand. But there's also a clue that the client can get more out of the representation.

My preference is 3. But is there a spec, best practice, or commonly used approach that can provide guidance which is the best choice?


Solution

  • The server may do any of the three, or it may respond with 406 Not Acceptable if it is unwilling to respond with a default representation.

    See: https://www.rfc-editor.org/rfc/rfc7231#section-6.5.6