What is the correct fallback if Content-Negotiation does not find a reasonable result due to a non 2xx status code? For example:
A client wants to download a PDF and sends following header Accept: application/pdf. Due to insufficient privileges the server would return a 403 Forbidden. You might want to explain the reason in more detail but it does not make much sense to return a PDF. How would you deal with that?
Should the server return an empty body? Should he ignore the Accept header and send some other representation like text/plain. Or is it the job of the client to provide alternatives per Accept: application/pdf, text/plain, */*.
Obviously if the user does not have permission to access the resource, there is no real alternative what a server can do. The server can however respond with content (even in an error case) which describes the error in more detail, if that response can be made using a media-type accepted by the client. The client should provide an Accept: header that describes all the media-types it can parse. So an automatic client would be able to do:
Accept: application/pdf, application/vnd.myapi.error
If content-negotiation fails, the returned code should be 406 Not Acceptable. The server can produce this if it can not provide any answer which would be acceptable to the client.
However, the specification states that the server may actually return an answer not explicitly acceptable by the client if it wants to, it is up to the client, to inspect the response headers to see what media-type the answer is.
Source: https://www.rfc-editor.org/rfc/rfc7231#section-3.4.1
Related
I know the difference between them generally but for the login form, I'm not sure why the POST method is recommended.
Broadly: because PUT has more specific semantics in HTTP, and those semantics don't match the typical login form case very well.
POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding 2009
POST /foo HTTP/1.1
Content-Type: text/plain
username=foo&password=this_is_a_secret
That request can mean almost anything; it might or might not be idmpotent, it might or might not be "effectively read only". It's very non-committal. From RFC 7321:
The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics.
In contrast, PUT means something much more specific
A successful PUT of a given representation would suggest that a subsequent GET on that same target resource will result in an equivalent representation being sent in a 200 (OK) response.
Thus
PUT /foo HTTP/1.1
Content-Type: text/plain
username=foo&password=this_is_a_secret
Suggests that when someone later does
GET /foo HTTP/1.1
You expect a response like
HTTP/1.1 200 OK
Content-Type: text/plain
username=foo&password=this_is_a_secret
In other words, the semantics of PUT are very close to those of "save" or "upsert". "Make your copy of this resource look like the payload of this request."
Remember, general purpose HTTP components don't necessarily know that these message are about "login"; they only see messages with semantics of the transfer of documents over a network domain. That's means that when they see your "login" PUT request, they are going to assume that the semantics are exactly the same as a PUT to any other resource on the web, and act accordingly.
i am trying to implement caching for dynamic API calls where data is near-static. The approach i have taken is using the ETag and returning an ETag header for a Web API response headers. However, Browser doesn't seems to return the "if-None-Match" header at all for me to validate the subsequent calls.
Please note that i am using https and i have a valid SSL installed. Anyone had this issue and potential clues?
Found the root cause of the issue, It was due to the wrong cache-headers being sent by the server particularly Cache-Control: no-store
After changing the response headers, Browser is now able to send the If-None-Match request header.
My current response header is as below which is good enough to request the browser to re-validate it.
If you have a REST service that accepts multiple formats:
JSON
XML
HTML form data
Is there a widely accepted 'default' Content Type or:
You pick it yourself based on the most frequent / common use case
Don't accept a missing content type, require it explicitly by consumer
For example, according to W3C the default content type for POST via HTML, is application/x-www-form-urlencoded.
I strongly suggest that a server should reject a request that has a missing or inappropriate Content-Type header. RFC 7231 Has an explicit code for such:
6.5.13. 415 Unsupported Media Type
The 415 (Unsupported Media Type) status code indicates that the
origin server is refusing to service the request because the payload
is in a format not supported by this method on the target resource.
The format problem might be due to the request's indicated
Content-Type or Content-Encoding, or as a result of inspecting the
data directly.
Even though it doesn't explicitly mention a missing Content-Type, this is the accepted practice. See: HTTP status code for unaccepted Content-Type in request
Just as you should send the content-type in a response, you should also expect to have a content-type in the request.
Also, it's quite common to expect the correct content-type, see Jira REST API for instance:
Make sure the content type in the request is set to 'application/json', as shown in the example.
Or Twilio, where they have a list of accepted content-type and say:
If the content-type header does not match the media, Twilio will reject the request.
And I'm pretty sure that also the Outlook Mail REST API needs it to be correctly set.
So, yes, I'd say:"Don't accept a missing content type".
Let's say that in my RESTful interface I require the client to include some special header, just to indicate it's an authorized client. (Trust me on this; it's a requirement of the project.) If the HTTP request contains an incorrect value in this header, the server needs to send back an HTTP response that the client can recognize that it sent an unsupported value in the header.
What's the appropriate way to send back this information using HTTP?
I could send back a 400 Bad Request response, but how do I tell the client what the problem was exactly? The obvious option is to include some message in the body of the response. But (besides issues of i18n) is it really a good idea for the client to blindly display the contents of an error message?
I could send back a 400 Bad Request response, with a proprietary special header indicating that such-and-such header had the wrong code. This has the benefit that the client can actually process what the error was (as opposed to free text in the content). So does the 400 response then become a catch-all response, with the actual error in some proprietary header? Is this a good general pattern? But that almost suggests...
I could could send back some arbitrary 4XX response that has a proprietary meaning, such as 472 Bad Foo Header Value. Microsoft seems to have gone this route at times. The obvious problem is the possibility of clashes in a future version of HTTP (or with others who have done the same thing).
I suppose I'm leaning more toward 400 Bad Request with a special header indicating the error specialization. Any thoughts or experience with this use case?
If the special header is incorrectly formatted then you could send a
400 Bad request Response indicating that the header is wrong.
However If the sole purpose of the header is authorization and you reject the header, because of invalid value, then I would opt for:
403 - Forbidden, if you want the connection to be refused
401 - Unauthorized, if the client should try to reauthenticate
In the Response phrase you can indicate the reason for refusing the connection.
I am building a web application which can accept resource representations via PUT, POST and PATCH in both x-www-form-urlencoded and JSON formats. If I receive a request body in another format, I would like to send a 415 response, plus some additional data declaring what formats I do accept (in a similar manner to the 405 response's mandatory Allow: header). I have seen on one answer at HTTP 406 and 415 error codes where the person answering did not know if there was such a mechanism defined, RFC 2616 mentions nothing in this regard, and some cursory Googling turns up nothing either.
I would like to just use Accept: even though that is defined as a request header. It seems most appropriate just to re-use it for this response. Do folks agree? Does anyone have a better suggestion?
Edit: I have since found Specify supported media types when sending "415 unsupported media type" which asks specifically if there is a standard for this. The correct and accepted answer was basically no, but the respondant there also had the same idea as me, that Accept would be a good header to use to provide this information. This prompted a message from Julian Reschke to the HTTP Working Group asking if it should be defined what sending an Accept: header in a response should mean. That email only received one response, which agreed that it was needed and that Accept seemed appropriate.
Note that I am not asking if I am permitted to send an Accept header, any header is allowed to be sent in either direction, but only those defined in the spec have meaning (semantics) to intermediaries, and also, any unexpected headers not prefixed with X- might clash with future versions of HTTP. This doesn't bother me.
As you said, Accept is a request-header. It is wrong to use it in a response.
To quote Wikipedia,
Content negotiation is a mechanism defined in the HTTP specification that makes it possible to serve different versions of a document (or more generally, a resource representation) at the same URI, so that user agents can specify which version fit their capabilities the best.
So it is the client who says in the request what media types he can Accept. If the server is not able to deliver this media type he responds with 406 Not Acceptable.
Since the client must be able to deal with the returned representation of the requested resource, it should specify which media types it can understand. It can specifiy multiple media types:
Accept: application/json, application/xml, x-www-form-urlencoded
If the client really wants to accept any media type, it can set
Accept: */*
The server will set a proper Content-Type response header even for such a request.
You receiving an unrecognized Content-Type will most probably be from a developer currently implementing a client to your service. Since there does not exist a mechanism for a server to advertise its supported content types, you might as well mention in the message body what types you do support.
I'm not aware of any standard mechanism to do this but you may be able to slightly re-purpose the Alternates header http://www.ietf.org/rfc/rfc2295.txt to do what you want.