I am trying to turn written documentation into an Open API 3.0 specification. The written documentation states that the use of the Accept Header is prohibited and Content-Type is required. How do I make that explicit in OAS3?
I can only find information on using media types for both Content-Type and Accept headers not how to make a difference between the two.
I also cannot find information on whether specifying a media type means that the Content-Type is required.
Any clarification is greatly appreciated.
Related
Suppose my HTTP server code implements the GET method on /example, replying with either JSON or HTML depending on the Accept header and setting Vary: Accept. The same data are also available without content negotiation at /example.json and /example.html, respectively.
Would I be using the canonical link relation correctly if I set Link: </example.json>;rel=canonical on /example when serving JSON, but Link: </example.html>;rel=canonical when serving HTML?
(A similar scenario could be constructed for entirely user-facing pages when using Accept-Language to choose the default language, provided that I don’t want to pay the cost of a redirect.)
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.
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".
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.