Skip to content

Why I’m giving REST a rest

March 13, 2013

So there’s quite a hype around REST lately, and I have to admit I’ve been on the bandwagon too. I’ve actually found it quite fun applying the constraints and trying to do things using a standard approach that will be familiar to other developers, and make my API easier to consume.

But recently I’ve become a bit disillusioned. I’ve tried to do a couple of things of late that I just couldn’t get to play nicely with REST:

  • Modeling many-many relationships, assigning or breaking links between resources via a REST API.
  • Bulk updates\inserts, or generally manipulating multiple resources at once.
spc

I frequently come up against the question of what makes an API RESTful, having a dig around, everyone seems to have opinions, but everyone seems to have questions too. Here are some that I’ve asked or that have come up in conversations recently:

  • Is it ok to have a URI that only accepts POSTs?
  • Is it ok to return a different representation on GET than the one expected by a POST to the same URI?
  • Is it ok to assign a URI to the relationships between resources and allow them to be manipulated via representations?
  • Can I update multiple resources by POSTing a composite representation?

Have a read through the comments in these two stack overflow questions, and you’ll quickly see what I mean:
http://stackoverflow.com/questions/511281/patterns-for-handling-batch-operations-in-rest-web-services?lq=1
http://stackoverflow.com/questions/969585/rest-url-design-multiple-resources-in-one-http-call

spc

So what is really RESTful?

RESTful architecture is governed by a set of key constraints… it must involve client-server interaction, be stateless and cacheable. It must be layered, i.e a client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way.

It must provide a “Uniform Interface”, which simplifies and decouples the architecture. Said interface is subject to a set of guiding principles:

  • Requests should identify an individual resource, and then a representation of that resource is returned. This representation is conceptually separate from the resource itself.
  • When a client has a representation of a resource, it should have all the information it needs to manipulate that resource provided it has permission.
  • Each request should include enough information to describe how to interpret the message, i.e specify a media type.
  • Hypermedia as the engine of application state (aka HATEOAS) – Except for entry points to the application, the client should be able to discover actions that can be taken for a resource based on the representation, e.g via hyperlinks or location headers.

You’ll notice I’ve not made any mention of HTTP verbs yet (POST, GET, etc), or status codes. Thats because these are actually incidental to REST… although it was designed on HTTP, it is not limited to the protocol explicitly. RESTful architectures can be built upon any protocol that is sufficiently expressive and has a sufficiently well defined interface. It just so happens that these constructs are very useful for this purpose.

spc

So whats the problem?

The key element that people seem to skimp on or miss completely is the fourth bullet above, or to paraphrase, a REST API must be hypertext driven. Here’s what Roy Fielding, father of REST had to say in 2008:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

For the lazy amonst you (shame on you), here’s are the key quotes

A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience

In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.

This is also precisely the element that caused me my initial problems. Its one thing to describe the way a resource is related to another resource through hypertext, but much more difficult to describe how you should go about manipulating those relationships… one way to do this is to expose the relationships themselves as resources, but that would require some prior knowledge that the approach was being taken… it’s not implicit.

And if you are performing more than one operation at once? You can’t use location headers… you can return a bunch of links in the body of your response detailing all the resources that were affected, but again you would need some explicit knowledge that those links were present in the body.

Some of us actually don’t see anything wrong with requiring the client have some knowledge of how to interact with the server. An alternative to HATEOAS is Client Server Domain Seperation (CSDS), which defines both client and server as bounded contexts, DDD style.

spc

So that’s why I’ve decided not to worry…

Take ‘Agile’ development as a case in point… most companies take some aspects of agile and use it to their advantage. But the vast majority of us still work to concrete deadlines; anyone doing this is in direct violation of the principles and so cannot be said to be truly agile.

It’s the same with REST… if you don’t make efforts to make your service discoverable then you cannot be said to be making a truly RESTful API. And as it turns out, doing so can sometimes be a bit of a pain. We’d all do a lot better to ignore ‘RESTfulness’ and focus on developing a sensible, easy to use interface.

So while there are all these people debating the finer points about how you should be using verbs or status codes, this is actually more about how to properly use HTTP in the implementation of a REST style architecture rather than what actually defines the architecture as RESTful.

Don’t get me wrong, I’m not going to stop using REST principles to guide good API design, they are sound principles. But from now on, I’ll only be using REST as a wordpress\stackoverflow tag so that people will still be able to find things I write once I stop using the term.

spc

Pete

spc

References:
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
http://en.wikipedia.org/wiki/Representational_state_transfer
http://stackoverflow.com/questions/511281/patterns-for-handling-batch-operations-in-rest-web-services?lq=1
http://stackoverflow.com/questions/969585/rest-url-design-multiple-resources-in-one-http-call
http://byterot.blogspot.co.uk/2012/11/client-server-domain-separation-csds-rest.html

Advertisements

From → REST, Web API

6 Comments
  1. I have long been advocating the term “HTTP Web Services” as opposed to “RESTful Web Services”. In my situation, (healthcare) a dogged adherence to RESTful principles just isn’t practical – a lot of our clients will struggle to implement HATEOAS in their solutions, and many of the services we are providing are real-time transactions, where the request and response are actually different ANSI transaction types.

    That said, a good working knowledge of RESTful principles has helped guide us towards better API design, and in my mind that is the most important thing that we have to get right.

  2. Anyone stumbling on the same issues (many to many, bulk updates, etc) should look at django’s tastypie. Works great for this.

  3. A complete and correct REST implementation shouldn’t have much trouble with a lot of the questions you raise (and the Wikipedia REST article, by the way, is so awful it shouldn’t even exist). I note you reference a post from Dr. Fielding, and I would suggest reading his actual publications, if you haven’t yet — maybe even slogging through his PhD thesis. REST as it is usually implemented is just wrong (Microsoft’s attempts are often among the worst). OpenRasta was a fantastic and very correct implementation, but as you probably know, Seb got distracted and eventually dropped it (and OSS in general, apparently).

    Yes, a POST-only URI is fine. There is nothing that says a URI needs to return anything, ever. (DELETE certainly does not.) A POST-only URI still identifies resources, and that resource can be strictly inbound to the server if that’s what makes sense.

    Different GET representations are fine relative to the POST representation. As you observe later, the representation is not the resource itself, it’s an abstraction, possibly many abstractions. The point and the value of content negotiation is to *encourage* multiple representations. Arguably a single POST URI could also support multiple representations (though it’s a bit hard to think of useful examples… allowing the upload of multipart document attachments could be one, I think).

    I believe your question of relationships as resources is a sign of insufficient abstraction in defining the resource that masks the underlying physical components of that resource. I believe most commonly the relationship would be a property of the resource, rather than a resource itself. That being said, I could probably imagine a relationship as a first-class resource in some scenario in which the type of relationship was potentially dynamic (versus merely changing what the relationship associates).

    It isn’t proper to ask if you can update multiple resources with a composite representation. There is no such thing as a composite representation, and the point of REST is to hide the physical, server-side implementation details from the client-side concerns. The POST body is the resource, period. If the server needs to break the resource apart to update multiple physical stores or elements, so be it. That is not a concern of the client or the RESTful URI schema.

    The point above is crucial. The most important thing REST does is divorce the client from ever having to know anything about what the server is actually doing. REST is more than just hiding the physical file structure – it’s also about abstracting EVERYTHING about the resources managed by the target site. Too many people, frameworks and publications treat REST as an API solution first that also happens to be able to serve up web pages, and that leads to thinking about REST schemas as SOAP-lite or a stand-in for CRUD behaviors, which leads to concerns like the one you raised. Just negotiate and manipulate resources needed by the client, and figure out how to handle the underlying resources on the server, behind the scenes, as it were.

    You wrote: “Requests should identify an individual resource, and then a representation of that resource is returned. This representation is conceptually separate from the resource itself.” But you can take it step further and also state that the resource itself is also separate from the underlying “physical” elements from which the resource is composed.

    I disagree with this: “When a client has a representation of a resource, it should have all the information it needs to manipulate that resource provided it has permission.” This isn’t really a requirement, though it is certainly “nice to have” where appropriate. It’s easy to imagine a URI which (for example) can return one representation for convenient quick-display purposes but another representation for modification purposes. Trivially, imagine a video archive — a static-image filetype list in the accepts header would return icons or still-frame grabs, but GETing the same URI with video formats in the accepts header would return the full movie clip.

    Towards the end, I think I see the main issue when you write this: “Some of us actually don’t see anything wrong with requiring the client have some knowledge of how to interact with the server.” There is absolutely nothing in REST that conflicts with that position — REST only requires that the “knowledge” originates with the server. My REST sites quite often pepper the HTML which goes back to the client with generated URLs and other server-side details that I do not hard-code into the page. It’s actually pretty easy to “start from nothing” with REST if you fully commit to the idea that the client knows nothing and the server controls everything — including stashing all state into the client as you go.

    I ended up here because of Superscribe. I loathe ASP.NET MVC and I’ve been looking for a good IIS-hosted .NET-compatible REST implementation after finally giving up hope that OpenRasta will rise from the dead. Your graph concept is pretty cool. Unfortunately it seems I found Superscribe in the middle of doc rewrites but I will definitely keep an eye on the project!

    • roysvork permalink

      Thanks for the comment… I will need to re-read when I have a bit more time to digest!

      For now though I just wanted to point you in the direction of http://superscribe.org where you’ll find hopefully all the documentation you need!

      Pete

      • Oh wow, fantastic, thanks. Very excited about this graph concept.

  4. Very interesting article and point of view! Thanks for the hints and for getting me to recap RESTfulness! 🙂

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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

%d bloggers like this: