Facilitating the spread of knowledge and innovation in professional software development



Choose your language

InfoQ Homepage News Is Proliferation Of Custom Media Types RESTFul?

Is Proliferation Of Custom Media Types RESTFul?


Subbu Allamaraju, revisits one of the recurring debates in the REST community; the standard media types vs. custom media types and tries to determine the best practices when using them. He starts with the stating dichotomous views on the use of media types.

  • Opinion 1: Web services must use standard media types to be RESTful.
  • Opinion 2: Custom media types are necessary to keep interactions visible, and to serve as contracts.

The first opinion which, if adhered to strictly, per Roy Fieldings thesis, “the use of media types such as application/vnd.example.myway+xml is not RESTful”. Subbu believes that understanding the impact of such media type usage in the real world is more important than following the thesis to the letter. There are however comments that suggest that this interpretation of the thesis might be up for debate as well.

To the contrary, the second opinion, he says, leads to visibility of the messages at the protocol level via the use of custom media types.

[…] For instance, how can anyone know if a representation that uses application/xml media type describes a purchase order, or a photo album? If the web service uses media types likeapplication/vnd.example.po and application/vnd.example.album, then any one can interpret the semantics of the representation without parsing the body of the representation. Per this line of thinking, a media type is an identifier for message semantics, and message recipients use media types to trigger processing code.

“So what is the right thing to do?”  He asks, as he puts forth his idea, in a effort to democratically determine the best practices

  • If the sender is formatting representations using standard extensible formats such as XML or JSON, use standard media types such as application/xml and application/json.
  • Mint new media types when you invent new formats.
  • If you are just looking for a way to communicate application level semantics for XML and JSON messages, use something else (e.g. XML namespaces and conventions).
  • If the goal is versioning, use version identifiers in URIs.

Giving java-like examples, He asserts that though its possible to peek into the messages to see how a request can be processed, it compromises visibility or opacity as the case may be.

Media types such as application/xml and application/json are good enough for XML and JSON message processing in code. […] URI based approaches are guaranteed to work across the stack. Ignoring real-world interoperability for the sake of "architectual purity" or "RESTful contracts" may eventually back fire.

Via the post is the solution presented by Subbu found the right balance between architectural purity and interoperable real-world solutions? Be sure to visit the original post to weigh in your opinion.

Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Community comments

  • Custom media types and coupling

    by Satadru Roy,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    Code extract from the blog:

    if("application/vnd.example.po").equals(response.getMediaType())) {
    // process purchase orders
    else if("application/vnd.example.album").equals(response.getMediaType())) {
    // process albums

    How is this any less coupled than the out-of-fashion RPC:

    processPO(poxml) or processAlbum(albumxml)?

    Not trying to be provocative just looking to be educated.

  • Re: Custom media types and coupling

    by Dilip Krishnan,

    Your message is awaiting moderation. Thank you for participating in the discussion.

    How is this any less coupled than the out-of-fashion RPC:

    processPO(poxml) or processAlbum(albumxml)?

    Not trying to be provocative just looking to be educated.

    I believe if u look at the larger use case picture the difference will be apparent. Think of an adhoc http client that requests for reprensentation of an album or po. The only coupling the client needs to have is the locations of the representations. Every other coupling can be either a client-just-knows kind or some out-of-band formal metadata exchange.

    Secondly the http method of interaction determines the nature of the operation safe/unsafe/idempotence etc unlike an RPC interaction.

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p


Is your profile up-to-date? Please take a moment to review and update.

Note: If updating/changing your email, a validation request will be sent

Company name:
Company role:
Company size:
You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.