The Central Problem in REST

So after much deep thought, I have uncovered the central problem in the modern interpretation of REST. I’ve had this nagging feeling that something doesn’t quite line up between “resource-oriented” design, and the restrictions on design declared for the sake of a “uniform interface”.

It’s not so much a problem with the original REST architecture, but a conflict between that original vision, and the notion of what we call RESTful these days.

Specifically, the “uniform” part of the uniform representation is there so a server can serve up data that a consumer can just pick up and render in a uniform way. So JPG images, HTML pages, and PDFs are all perfect examples. A browser just gets the data, then renders them. It doesn’t know or care what’s inside the representation, because it conforms to a uniform standard.

But the moment you have your REST service send back an application-specific representation, it’s not uniform anymore. Suddenly the client needs to know what the fields *mean* in order to use that information.

And it doesn’t matter if you’re using the HTTP verbs or not. As soon as you return any representation that only a specific set of clients are specially coded to understand, then it’s not uniform anymore.

The classic example where this shows up is the problem REST has with search. All the search engines have different URLs for their searches, and all of them return different representations. So they are, on their face, not uniform.

Another place where the central problem shows up is schema versioning. If the client can only understand a certain version of the representation, that conforms to a specific schema, then REST doesn’t have a good answer for that. The community is trying to come up with an acceptable standard: use content negotiation, put it in the URL, put it in a query string, put it in a special header? But there isn’t a clear answer, or a clear winner, because REST isn’t about how to manage non-uniform resources.

Designing your service interfaces closely to the HTTP spec is a good idea, and leads to nice clean design. But it still isn’t consistent with REST, even if you disavow RPC and use all the HTTP verbs right. But then we should stop talking services and how REST-ful they are, and start talking about HTTP-ish they are. Citing REST just doesn’t work when you’re serving up specialized, non-uniform application data that requires specialized logic on the client side.

In the end, it may turn out that REST just isn’t an architecture well-suited to the purpose of sending around application data.



Filed under REST

4 responses to “The Central Problem in REST

  1. Pingback: This Week in #REST – Volume 11 (Apr 5 2010 – Apr 11 2010) « This week in REST

  2. I don’t think I fully understand what’s bugging you, but here are some thoughts.

    I do think REST is cool for sending application-level data. It’s just that web browsers are not general all-knowing REST user-agents. They are application-specific and process a finite set of specific media types. If your application requires a new media-type which the browser doesn’t understand (WRT rendering) – then it’s no game. However, you can create your own user agent which does understand that media type.

    I don’t see how you could even create a user-agent that up front understands all possible media types since you can define new media types at any time. Either that or we define a fixed set of media types for all times…

    This is why the media types which the application uses are considered the contract of RESTful services. Glance over the answers at

    • roby2358

      Oh, I agree. I was just trying to be provocative. Right now I’m kind of blowing up REST in my head so it will come back together in the right shape. I hope.

      I do think there’s a central problem, there, though that the current formulation of REST doesn’t addresses. If you specify content-type as “application/xml” or “application/json”, then great, you really are transmitting state information in a broad, generalized standard.

      But if you want to tie an XSD schema to that XML, the model starts to break down — and you have to get creative about how you do it. And that creativity weakens the “uniform” part of the design constraints.

      The problem is that the XSD will probably change more rapidly over time than the XML spec does. Also, the application XSD is not a broadly-defined standard, but one specific to some dev team’s implementation.

      (Right now) I’m thinking that the best answer is to handle data the way browsers currently handle javascript/json — as dynamically-typed structured data, and the user agent needs to be flexible about what it gets back.

      The extreme would be to create a Big Generic Single Schema that defines elements like <object> and <property>, and shove all your data into that.

      Otherwise, if a client needs to put restrictions on the representation, then that restriction belongs in the URI somewhere.

      I probably should have said that I think versioning application data, within a broad standard like XML or JSON, is better addressed as a resource/representation problem than a uniform content type problem. But I’m not sure that’s right either.

      Also, how is saying it that way fun?

  3. Matthew W

    Think of it this way: data can be represented and consumed at various different levels of semantic structure.

    RESTful APIs tend to work best when the representations allow the dataset to be understood, navigated and interacted with at unstructured and semi-structured levels. But that doesn’t at all mean that they can’t have additional structure on top of that which particular applications can exploit.

    The representation media types should allow generic manipulations to be done (where possible) by generic clients, but may also allow specialised clients to perform specialised manipulations.

    For example, a RESTful API might allow, for resources which expose an application/ representation:

    * A WebDAV client to GET and PUT these representations for storage purposes without understanding anything about their meaning

    * An XML editor to display and manipulate the tree of XML in a generic way, maybe download its schema and present some generic functionality based on the schema metadata

    * A client (eg a spider) which knows about standards for expressing link relations in XML schemas, to traverse the resource graph and potentially present a generic hypermedia UI for the link relations it finds

    * A client which knows about the precise semantics of your application-specific schema, to perform application-specific manipulations and present an application-specific UI for them

    * A more recent version of that client to exploit extra fields, extra link relations etc in more recent versions of the media type, which the older version had no knowledge of, but without unnecessarily compromising backwards compatibility

    That help at all?
    I’ve been battling with this stuff too… I think really we need some good standard media types for exposing a CRUD-able structured object graph in a generically-introspectable way. With these most structured object-based APIs could be manipulated by a lot of useful semi-structured tools in a RESTful way.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s