How should an a REST API handle HTTP 415 ?

[miqui]

How should an a REST API handle HTTP 415 ?

..thanks...

rgds,

Miguel

[sune jakobsson]

This occurs when the server is unable to match the requested content typ. It really does not have anything to do with the API it is merely an indication that the server does not support the requested content type.

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Dietrich Schulten]

Following https://tools.ietf.org/html/rfc7231#section-6.5.13, HTTP 415 indicates to the client that it has sent a payload which cannot be processed with the requested method on the given resource, because the media type of the payload is not suitable. Like, you sent a picture when plaintext was expected.

A rest api should respond with 415 if a client makes this kind of error. The API may offer a media type with support for hyperlinks which informs the client what it is supposed to send to make life easier for the client (collection+json, uber, hal-forms, siren, hydra, hyper-json-schema or of course html), or it could indicate a profile to overlay an existing mediatype with additional semantics by sending a profile link header, where the expected mediatypes of request bodies could be part of the profile description.

Your question might also mean, how should a client handle a 415 response. Sometimes it just failed to send a Content-Type header matching the payload. 

If an api uses no hyperlinks and no profile link header, your only hope is some out-of-band documentation, i.e. the api's website or a swagger page.

Also see https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven for some conceptual background.

Best, Dietrich

--