Is the semantic of the data integral part of REST?

Question

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. :-)

Typewritten

Answer 1

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.

Gnathonic

Answer 2

I don't see the need to be overly pedantic about it. A resource can expose multiple representations; each with its own semantics (and even multiple dimensions of semantics at that). If one representation doesn't provide the semantics required by a particular use case, expose one that does.

Thus, a client that does not understand the data, can still consume the REST API.

I'm not sure that's a good litmus test for what does or does not make a decent representation. What good is a client that can consume a document but not understand it well enough to do anything with it? I guess I don't understand how "basic processing of resources" makes application/xml a better choice than some arbitrary blob of 1s and 0s?

Since you asked for references, here's an article from Roy Fielding where he "proposes" a bitmap representation of social network graphs. I can certainly get a machine to display these bitmaps, but of what use is that if I don't understand the underlying social network graph? Would changing the representation to application/xml allow a naive client to extract additional meaning from it that isn't contained in the bitmap? Nope.

Guck

Well, the question is not if it's a decent representation, but whether it's still acceptible to call the API RESTful. :-) – Typewritten

I guess that's where I don't see the need to be so pedantic. Some representations will naturally be more meaningful to certain clients than others. I guess I thought this was a discussion about the quality of semantic-less representations, not about reaching a consensus of what can be called REST – Guck

The bitmap example is an interesting one because it infers that the API would return an image media type but that there is more semantic meaning than just the visual produced by the pixels. That definitely contradicts my previous understanding of what Roy was saying. – Eating

Honestly, I have no idea at this point which side of the debate I'm on. I feel like I was arguing for and against both of you :) – Guck

Answer 3

Check out this set of slides from Mark Baker for more explanation as to why application/xml does not satisfy the "self-describing" constraint. You can also read a number of posts on his blog including this one where he continues to explain why application/xml + namespace is not equivalent to media-types.

Eating