

Why and How You Should Write REST-Centric Applications - mwbiz
http://www.w2lessons.com/2011/05/why-and-how-you-should-write-rest.html

======
clarkevans
Using HTTP status codes for error messaging leaves quite a bit to be desired.
You don't have that many options beyond a handful in the 4xx (400, 404, 409)
and 5xx (500, 503) range. For the most part, they are either really general or
too specific to be correctly used. It'd be nice if there were a standard for
supplemental error messages.

Edit: (to the downvoter) this post explicitly mentioned "You get clean
exception handling via HTTP status codes". The exception handling may be
clean, but it's extremely coarse.

------
methodin
RESTful APIs can be a pain when you have to mashup different APIs, though. The
amount of calls you end up having to do can be quite a lot. From a backend
standpoint it's not that bad if you cache, but from a consumer standpoint I
have to get a /users/active list, iterate over them, then call a /friends/[id]
call for every user. If you add a third list you can easily see how annoying
it might be. It's great that your APIs can be so flexible but now your clients
are writing completely different code all over... the chances of you breaking
something or them having to re-code things every release is a lot greater than
updating a getFriendsOfActiveUsers traditional API call. Has anyone else found
this to be the case? Are there ways around it? I'd almost want a hybrid or a
mash API that I can pass in URLs and have it return a mashup for me.

~~~
notJim
This is an issue I'd like see more people talk about in REST API design.
There's quite a balance to be struck between the number of calls to be made
and the size of the data that needs to be download.

I designed a REST API that's primarily (well, currently only) used for mobile
applications, and it was often hard to decide whether to “denormalize“ the API
(fewer API calls required, but more data per call) or provide very general
fine-grained resources.

~~~
ataggart
One need not exclusively describe every sublist as a separate resource.
Sorting and filtering can correctly be implemented as query params on the full
list resource. Perhaps the shunning of query params (rightfully so when used
as verbs) has gone too far.

~~~
smackay
Hear, hear. REST APIs are particularly difficult to implement when you have
multiple optional value to query/describe a particular set of resources. The
RESTful way encourages an explosion of URLs to try and support the different
combinations. Adding new ways to list resources at a later date is also next
to impossible. Query parameters simplify the process and the API significantly
and still make it easy to describe and use. For me the best approach is to mix
the two: make often used, pre-defined queries RESTful then support all the
specialised combinations through query parameters.

------
DocSavage
I was introduced to RESTful APIs when Rails started championing them. And
while I've read a number of REST articles, it still seems like I'm not
understanding the nuances of long-term vs short-term decoupling of
client/server to the level that Fielding demands for REST. For example,
there's his blog entry here:

[http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hyperte...](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-
driven)

A key point is this paragraph:

"A REST API should spend almost all of its descriptive effort in defining the
media type(s) used for representing resources and driving application state,
or in defining extended relation names and/or hypertext-enabled mark-up for
existing standard media types. Any effort spent describing what methods to use
on what URIs of interest should be entirely defined within the scope of the
processing rules for a media type (and, in most cases, already defined by
existing media types). [Failure here implies that out-of-band information is
driving interaction instead of hypertext.]"

\---

When I try to absorb this and other points in that blog entry, I feel like
I've failed to understand the real lessons and I'm thinking too short-term
with fixed URIs for CRUD on data. But then again, in the comments, Fielding
says "REST is software design on the scale of decades: every detail is
intended to promote software longevity and independent evolution. Many of the
constraints are directly opposed to short-term efficiency."

This makes a lot of sense to me and suggests that truly RESTful design isn't
necessarily the best fit for people who want to throw stuff up on the web and
then evolve to a more stable API.

~~~
extension
The lessons of REST are straightforward in the context of human-machine
interaction. The common confusion happens when trying to apply it to machine-
machine interaction. I've never seen anyone make much of a case for REST in
that context, not even its creator.

If the server can evolve new functions independent of the client then it seems
to me that the client has to evolve new intentions independent of the server.
At present, clients can only do that with a human operator.

------
sradnidge
Nice post. The single biggest criticism I usually level at REST
implementations is the lack of HATEOAS - the discoverability aspect of REST is
about more than just an easily understood URI. As the author of this post
states in his 2nd bullet point (emphasis mine):

"It’s expressive, REST paths and CRUD requests are easy to understand _and
hypermedia makes it easy to navigate_"

It's that second part that so many implementations gloss completely over, it's
probably worth discussing that separately in the same way that authentication
is discussed in the post.

~~~
seangeo
I agree that this is often glossed over. In fact I can't think of any
framework implementation that provides it.

About the best example I can think of is the Atom publishing protocol where a
service links to it's publishing URLs and a feed can provide pagination
through hyperlinks. But still it is not a particularly sophisticated example,
do you know of any others?

~~~
extension
I'm not sure how HATEOAS could be bundled into a framework as there is no
straightforward process for realizing it. Designing a generic hypermedia
format is a huge undertaking and a RESTful service must be almost completely
specified by such formats.

If you can implement your service entirely with existing formats, that could
make things much simpler. But the only kind of hypermedia for machine data
access that I've ever heard of is RDF, and there is nothing simple about that.

------
Sym3tri
Authentication and need for at least a pseudo "session state" always seems
like the trickiest part of building a 100% RESTful app. Anyone have
details/examples on ways to address these?

~~~
ataggart
One approach I've seen regarding auth is to use a faux-resource:

Login:

    
    
        PUT https://example.com/credentials
        {"username":"foo", "password":"bar"}
    

Check if user is logged in:

    
    
        HEAD http://example.com/credentials
        Cookie: ...
    

Get current user:

    
    
        GET http://example.com/credentials
        Cookie: ...
    

Logout:

    
    
        DELETE http://example.com/credentials
        Cookie: ...
    

From the point of view of the one client, it's no less "real" than any other
resource.

------
stretchwithme
Seems like the Rails guys have done a good job sorting all these issues out.

