This is a follow up on a question asking for an explanation of REST.
As you can see from the comments to my answer, we’ve had a small argument with Darrel Miller on the best media representation of the resources. We’ve had a further email discussion that resulted in this question.
The main difference between Darrel’s and mine understanding of REST is whether the semantic of the data is part of the REST API.
Darrel believes (my interpretation of his words :-)) that the semantic of the data is an essential part of the REST API and as such, the media representation choosen should reflect it. Thus, a proper REST API should choose either:
- a well-known media like ATOM to represent the data, so that as many clients could understand the semantic of the resource natively;
- an app-specific media type like application/vdn.mycomany.mymedia and expect the client to understand this media type to be able to consume the resources data. Application/xml is not a good resource representation, as it does not represent the semantic in the media type, yet requires the client to know more about the semantic.
I, on the other hand, believe that the REST API is a separate layer from the actual data representation. The media type exposed by the API is just a container to transfer the resource data. The actual semantic of the data is treated separately. Thus, a client that does not understand the data, can still consume the REST API. Application/xml is a really good data representation, as it allows tight coupling for clients that understand the schema, yet still allows client that don’t understand the schema to do some basic processing of the resources.
Thus, the question: is the data semantic part of the REST API? Should we choose only media types for resources representation that actually represent the semantic of the data as well?
I would appreaciate if people post in their answers some citations, preferably from the Roy man himself. 🙂
Let’s start at the beginning: media types are there to provide the client with a format it can use to decide what to do next. Without an html page, the browser has no links to go to. Without an html renderer, the browser cannot render a page and won’t know what to do.
Without a media type, the client has no clue if it will be able to do anything with the byte stream. Indeed, when a client receives the headers specifying application/xml, it has no knowledge of what to do beyond get an xml parser.
So the question really is, should the client be able to make a decision based on the http message without having a look inside the message, or should it go and peek inside the message (or worse, parse the message first) to know what to do.
Lack of media types means that your client will have to do additional peeking work, or worse process the entity body itself, before it can make a decision, be it for rendering or for processing. You now have to add a lot of custom behavior for each of your formats you may want to process, and you loose a bit of coupling in the process.
It’s also an http fundamental that intermediaries should be able to process the requests without inspecting the body, and there as well application/xml is problematic.
Now when you say that the semantic of the media types is part or not of the API… What constitutes the API?
From a client perspective, there is no API. There is an initial representation that lets the client make a decision as to what to do next. The media type is indeed where the client gets the information it requires to navigate the ‘API’, and as such there can be no API without representations.
Furthermore, a client should have only three bits of knowledge: a bootstrap location, the HTTP protocol and the media types. The first is only a URI and doesn’t convey much beyond the location of a represetnation needed to continue. The second has already very clear semantics. The third is the one where you have control, as it’s the contract you have with your client.
That contraact says that whenever you want to do something, the something will have semantics: to add a customer, send a application/vnd.acme.customer+xml to /customers using a POST.
Hence my answer: designing a REST architecture relies on two steps: resource modeling (at the conceptual level) and media type building. Anything else and you’re likely doing it wrong.