Although it isn't stated directly in IETF RFC 6838, after reading the text (and consulting wikipedia) one can conclude that the general schema of a Media Type is as following:
type name / [ tree. ] subtype name [ +suffix ] [ ; parameters ]
Both Content Type and Accept HTTP Headers use Internet Media Types (as stated in RFC 2616).
RFC 6838 also states the following about "+suffixes":
"+suffix" constructs for as-yet unregistered structured syntaxes
SHOULD NOT be used, given the possibility of conflicts with future
suffix definitions.
RFC 6839 defines the following registered suffixes:
"+json", "+ber", "+der", "+fastinfoset", "+wbxml" and "+zip"
Now, take the following data:
{
"title": "<h1>Some formatted title</h1>",
"body": "here's a <b>long</b> formatted text with <i>stuff</i>"
}
.
Is text/html+json a good media type for this?
What if, instead of JSON, I use YAML? (text/html+yaml violates RFC 6839 since it's not registered)
And what if I want to build a parser that decodes data based on Content Type? Should I look for "subtype" or "suffix" for the appropriate "encoding"?
RFC 2616 is obsolete. Please look at RFC 7231.
I wouldn't use html+json for something that is a mix of HTML and JSON; you'd really need to translate all markup to JSON (at which point you'd realize that JSON doesn't work well for markup languages).
But yes, you could use something+json, as long as you register.
+yaml doesn't violate RFC 6839; but you would need to register it.
Generic software can use the suffix to select a parser. XMLHTTPRequest's support for +xml is an example.
Related
In a 406 Not Acceptable response:
The server SHOULD generate a payload containing a list of available
representation characteristics and corresponding resource identifiers
from which the user or user agent can choose the one most appropriate.
A user agent MAY automatically select the most appropriate choice from
that list. However, this specification does not define any standard
for such automatic selection, as described in RFC7231 Section 6.4.1.
Is there a preferred format for that "list of available representation characteristics and corresponding resource identifiers"?
I can send a response like:
{ Acceptable: ["application/json", "application/pdf"] }
But then I am assuming a default Content-Type for the 406 payload (JSON in this case).
Or should I send a very simple, almost format-less, payload like:
application/json,application/pdf
Is there a preferred format for that "list of available representation characteristics and corresponding resource identifiers"?
There's no standard for such payload.
You could choose any format that can be easily parsed by the user agent. In practice, both JSON or text should be fine:
{ "acceptable" : [ "application/json", "application/pdf" ] }
application/json,application/pdf
See the following quote from the section 6.4.1 of the RFC 7231, which is referenced in the 406 status code definition:
[...] A specific format for automatic selection is not defined by
this specification because HTTP tries to remain orthogonal to the
definition of its payloads. In practice, the representation is
provided in some easily parsed format believed to be acceptable to
the user agent, as determined by shared design or content
negotiation, or in some commonly accepted hypertext format. [...]
MDN Web Docs from Mozilla suggests the following:
[...] In reality, this error is very rarely used: instead of responding using this error code, which would be cryptic for the end user and difficult to fix, servers ignore the relevant header and serve an actual page to the user. It is assumed that even if the user won't be completely happy, they will prefer this to an error code. [...]
How could I understand this record:
Accept: application/vnd.my.api+json
I mean, is this "+" symbol is standartized (anyway, I have not find it in spec), or it is just a convention?
Thanks.
The Accept header specifies a list of acceptable media types.
The "+xxx" part of the media type is called suffix. It is an augmentation to the media type definition and helps to specify the underlying structure of that media type.
RFC 6838, "4.2.8. Structured Syntax Name Suffixes" defines:
XML in MIME [RFC3023] defined the first such augmentation to the
media type definition to additionally specify the underlying
structure of that media type. To quote:
This document also standardizes a convention (using the suffix
'+xml') for naming media types ... when those media types
represent XML MIME (Multipurpose Internet Mail Extensions)
entities.
That is, it specified a suffix (in that case, "+xml") to be
appended to the base subtype name.
Since this was published, the de facto practice has arisen for
using this suffix convention for other well-known structuring
syntaxes. In particular, media types have been registered with
suffixes such as "+der", "+fastinfoset", and "+json". This
specification formalizes this practice and sets up a registry for
structured type name suffixes.
The primary guideline for whether a structured type name suffix is
registrable is that it be described by a readily available
description, preferably within a document published by an established
standards-related organization, and for which there's a reference
that can be used in a Normative References section of an RFC.
Media types that make use of a named structured syntax SHOULD use
the appropriate registered "+suffix" for that structured syntax
when they are registered. By the same token, media types MUST NOT
be given names incorporating suffixes for structured syntaxes they
do not actually employ. "+suffix" constructs for as-yet
unregistered structured syntaxes SHOULD NOT be used, given the
possibility of conflicts with future suffix definitions.
I'm implementing an API method that allows for exporting some data to a file. The format of the file is selected by the caller of the method.
The API method currently has an URI-form like so: /customers/{customerId}/shoppingchart/export/{fileTypeId} but what is the "correct" Http-way, if any, to implement the file type selection? Should the choice be specified by the Http Accept header or in the URI or some other way? And, what is the correct status to return if the asked format isn't supported?
I agree with the HTTP Accept header to specify the file type.
RFC 2616 states:
The Accept request-header field can be used to specify certain media types which are acceptable for the response.
However this does not indicate whether you can create your own custom types (should you wish that).
The HTTProtocol describes an Accept header as this:
This field contains a semicolon-separated list of representation schemes (Content-Type metainformation values) which will be accepted in the response to this request.
The above link then points to the definition of a Content-Type exactly. What's important here is
The x- convention for experimental types is of course still available as well.
This tells us that we can define our own custom types in an Accept header given that we prepend them with x- (e.g. x-ext for .ext files) as is common in the HTTProtocol.
What is the correct status to return if the asked format isn't supported?
I would argue HTTP 415 - Unsupported Media Type as defined in section 10.4.16 is appropriate here.
The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
Is this a valid http url
http://www.example.com?x&y
or
we must always have = sign for parameters.
http://www.example.com?x1=x&x2=y
Well, it works, and the W3C recommendations are extremely general -- only the use of ? and + are defined. So I think from the perspective of HTTP/HTML the = is optional. It's use is obviously a common convention and many client & server libraries use it, but there doesn't seem to be any reason you couldn't define a service to work on some other scheme.
Anecdotally, I like to leave out the =blah part when I'm using the query string as a flag as in http://www.example.com?logout
Reference: http://www.w3.org/Addressing/URL/4_URI_Recommentations.html
According to the ABNF in Appendix A of RFC 3986, both examples above are valid URL.
Note that if you read only the Wikipedia article on Query string, you might get the false impression that the second ne is the only valid one.
What is the most appropriate media type (formally MIME type) to use when sending data structured with YAML over HTTP and why?
There is no registered application type or text type that I can see.
Example:
> GET /example.yaml
< Content-Type: ????
<
< --- # Favorite movies
< - Casablanca
< - North by Northwest
< - Notorious
Possible options:
text/x-yaml
text/yaml
text/yml
application/x-yaml
application/x-yml
application/yaml
application/yml
Ruby on Rails uses application/x-yaml with an alternative of text/yaml (source).
I think it's just a matter of convention, there is no technical why, as far as I can tell.
Although another answer was accepted, please refer to this Proposed media type registration for YAML thread on the IANA mailing list for reviewing Media Type in which Ben Harris, University of Cambridge Information Services, proposed in July 2015 on behalf of the YAML team the media type:
text/vnd.yaml
with (suggested) deprecated aliases:
text/yaml
text/x-yaml
application/x-yaml
That is still proposed/pending (the thread does not indicate status of the proposal) so this answer is no more definitive than the others :-)
I'd say text/x-yaml:
text over application because it's a human-readable
x-yaml over yaml because it hasn't been accepted into the registered list of mime types.
Edit: from RFC 3023 (XML Media Types):
The top-level media type "text" has
some restrictions on MIME entities
and they are described in [RFC2045]
and [RFC2046]. In particular, the
UTF-16 family, UCS-4, and UTF-32 are
not allowed (except over
HTTP[RFC2616], which uses a MIME-like
mechanism).
Interesting... Not exactly sure what it means, but food for thought.
On Chrome application/yaml will download, while text/yaml will display.
"x-" media types are discouraged, see RFC 4288, Section 3.4. The right thing to do is to use the personal tree, the vendor tree, or to actually attempt a proper media type registration.
The IETF is working to register the application/yaml media type and the +yaml structured syntax suffix.
Currently, we are not registering text/yaml. https://github.com/ietf-wg-httpapi/mediatypes/blob/main/draft-ietf-httpapi-yaml-mediatypes.md
Feel free to participate in the discussion.
As per MIME Types list it's text/yaml, even though it's not in official IANA MIME list