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".
Related
I'm finding it hard to understand if there are any implications of asking for a content-type header for GET requests.
I know that usually one should use accept header for GET, but what are the implications of using a content-type?
Basically Content type is used for the Content you are sending!
We can have multiple content type while sending Request, Could be JSON, XML and others etc.
Using content type will specify the server and Client that the Content we will send will be a JSON, XML, or any other type.
In REST API, I was checking recommendation to version API with accept header as:
Accept: application/vnd.com.myservice.v2+json
Now, server can extract this information and send v2 response. Why are we sending vnd.com.myservice.v2 in accept header where we should only send Accept: application/json? Why shouldn't we create separate header for this?
Accept is a standard header and is used in media type negotiation. The media type determines how a resource is represented over the wire. Ultimately, that is the API version - just representation of resource.
Accept also has other useful semantics that a custom header doesn't. For example, Accept allows for multiple, quality (e.g. weighted) media types. A client could ask for:
accept: application/vnd.com.myservice.v2+json;q=0.8, application/vnd.com.myservice.v1+json
This indicates to the server that the client prefers V2 of the JSON format with a 80% weight. If it's not available, then the client will also accept V1.
A media type can also use custom parameters. The following is also valid:
accept: application/json;q=0.8;v=2.0, application/json;v=1.0
This says the same thing, but uses a standard media type with a custom parameter instead of a custom media type. This approach is more generic and generally easier to consume in web stacks (in my experience).
I hope that helps.
I have api that is exposed to multiple clients. They all when requesting any resource send me a "sourceId" through which i identify which client the request is coming from:
Should i accept "sourceId" in body or in headers? How would it impact in the future?
Headers make more sense as this is something that would remain static for a particular client but i can't think of a good reason as to how i can decide which parameter to send in body and which in headers?
For some HTTP methods, such as HEAD, GET and DELETE, the request payload has no defined semantics and sending a payload body on a such requests might cause some existing implementations to reject the requests. For further details, check the RFC 7231, the current reference for semantics and content in HTTP/1.1.
Sending the parameter in a HTTP header should work for all HTTP methods though.
If the source identifier is an API key or it's used for authentication, it should be sent in the Authorization header. There are many APIs that define custom HTTP headers like X-API-Key or X-Source-ID. I would avoid that though.
The main reason for it to be in the header is that not all rest methods have a body, for example GET. In most cases the data your request is interested on would be in the body, but information about the request itself would be on the headers.
For example if you want informarion about your sourceid then it would be either in the body or as part of the uri, but if the sourceid is just a way to authenticate the caller when asking for information about something else then it would be in the headers.
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
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.