

Your Web Service Might Not Be RESTful If… - psadauskas
http://www.theamazingrando.com/blog/?p=107

======
paul
Fortunately, I don't care.

The broad concepts of REST are good, but this pedantic stuff is so silly.
There's a reason that most popular APIs will fail this test -- the people who
built them were thinking about more important issues than achieving some kind
of religious purity.

~~~
jimbokun
"There's a reason that most popular APIs will fail this test -- the people who
built them were thinking about more important issues than achieving some kind
of religious purity."

What issues are those? The article does give reasons for each recommendation
that go beyond an appeal to RESTful Authority. I would be curious to hear how
the criticized techniques solve some important issue better than the article's
recommendation. For example, is there a specific reason that API tokens are
better than Digest authentication?

~~~
bsaunder
Perhaps creating real business value.

------
jasonkester
Nice to see the way it's 'supposed' to be done, but really that's a lot more
complicated than it needs to be. Most APIs can get away with "HTTP requests
that do stuff".

As an example, here's how you create a new meeting with Twiddla's (evidently
RESTless API). One POST over SSL:

    
    
      > POST https://www.twiddla.com/new.aspx
      >      username=billy
             password=iLikeRainbows
      
      < HTTPS/1.1 200 OK
      < 109232
    
    

Now, here's how this author suggests people do it:

    
    
      > GET http://api.twiddla.com/
      
      < [XML packet full of endpoints comes back]
      
      > GET [endpoint you parsed from that list]
      
      < HTTP/1.1 401 Authorization Required
      
      > GET [same endpoint after jumping thru crypto hoops]
    
      < HTTP/1.1 200 OK
      < 109232
    
    

As an API publisher, I can see absolutely no value in making my users jump
through all those hoops just to use my API. The API exists so that people can
get things accomplished on my site, and I don't see any reason why it
shouldn't be just as usable as the site itself.

Please, if you're putting out a simple API, don't make it overly complicated
just to please this author and others like him. Make it exactly as complicated
as it needs to be to perform the task intended and no more.

~~~
Andys
Well he's just spelling out the steps to explain HTTP Digest.

In the real world, any HTTP client library worth using already implements HTTP
authentication transparently to you, the API consumer.

~~~
jasonkester
That's actually surprising, that the default behavior for a
HttpWebRequest.GetResponse() method would be to parse the response and decide
to send off a second request automatically. I would expect some developer
involvement would be required.

Regardless, assuming I'm using your library, I'd still need to do a request,
some XML parsing to discover the right url, followed by a second request, just
to get back the response I want. Compared to 1 request, that's still 3 times
the effort for no added benefit.

~~~
jamie_ca
If more people did proper restful applications, perhaps there would also be
proper libraries for interacting with them? Perhaps something that looks like
this (with a ruby flavor):

RestfulApi.new('<http://api.twiddla.com/>, :user => 'billy', :password =>
'ILikeRainbows').post('Meetings')

~~~
psadauskas
Yes, exactly. I've written a (rough) DataMapper adapter for interfacing with
them.

    
    
        class User
          include DataMapper::Resource
          resource_name "AllUsers"
    
          # define some properties
        end
    
        User.first(:login => "admin")
    

<http://github.com/absperf/dm-ssbe-adapter/tree>

------
codyrobbins
At the end of his article the author says, 'Now you don't have any excuses.' I
respectfully beg to differ. I think the 'proper' way of doing things he
describes is much more work for the clients of the API. The benefits to the
clients he describes, such as not being mercy to changes in the API's URL
structure, are indeed benefits, but they're not guaranteed to be realized, and
it's questionable whether they would pay for the extra work required.
Implementing the API as described would allow clients to create client apps
more tolerant to changes in the API, but the additional work required to take
advantage of it may be more of a barrier than a help. In a perfect world, the
clients would have the time to do so, but in an imperfect one it probably just
makes more sense for them to update their app when the API changes and munge
some URLs with a shell script.

The author also conveniently ignores a glaring detail that always makes me
angry when people talk about REST as something people should adopt. The simple
fact is that browsers don't support REST — no browser supports the PUT or
DELETE methods, not to mention other things in the stack like the web server.
Yes, Rails has built-in support for REST, but it's accomplished via a
disgusting hack whereby hidden form variables are sent to mimic non-supported
verbs.

I've always felt that saying that people should adopt REST when browsers don't
even support it is like saying people should switch to wind power when there
are no wind farms producing it. Nice in theory, but not practical and far more
trouble than it's worth.

~~~
blasdel
Sorry, but browsers absolutely support arbitrary HTTP methods, and have since
IE6. XMLHttpRequest, have you heard of it?

Also, REST != PUT + DELETE. Don't get hung up on it, they're just surface-
level niceties. The real point is to not mix up GET & POST, to be careful
about state and idempotence.

~~~
codyrobbins
[http://en.wikipedia.org/wiki/Representational_State_Transfer...](http://en.wikipedia.org/wiki/Representational_State_Transfer#Implementation)

------
JimmyL
>> You have an “API/Key/Token” in a header or a url.

This - specifically, how to do user authentication/access control in a RESTful
manner - has always puzzled me. The author suggests HTTP Digest
authentication, but that seems to fly in the face Roy Fielding's commandment
that a RESTful interface shouldn't depend on the communications protocol being
used; HTTP Digest seems pretty tightly coupled to HTTP, no?

Broadly, what are some of the canonical ways to do user authentication while
still keeping close to the theoretical/theological underpinnings of REST?

~~~
alexandros
RESTful interfaces should NOT be ptotocol independent. While REST can be
implemented over multiple protocols, a RESTful interface is by definition
tightly coupled to the protocol it goes through. For instance REST specifies
that we should use a uniform interface, but HTTP tells us what that interface
is, and a REST over HTTP interface (the most common RESTful interface) has to
respect that. I would be interested in where you read this fielding quote as
this 'protocol inependence' and its problems is a common charge he makes
agains WS-* if anything.

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

Specifically:

 _A REST API should not be dependent on any single communication protocol,
though its successful mapping to a given protocol may be dependent on the
availability of metadata, choice of methods, etc. In general, any protocol
element that uses a URI for identification must allow any URI scheme to be
used for the sake of that identification. [Failure here implies that
identification is not separated from interaction.]_

~~~
alexandros
Well, Roy has a way of describing things from a Systems Engineering
perspective. that can confuse when read from people with a different context.
I think where HTTP digest etc. comes in is the 'successful mapping' bit. While
the abstract API should not specify HTTP digest, the materialised API that
people actually use (the mapping of the API onto HTTP) should.

------
drawkbox
Good points. I think that people resort to URL based versioning and api keys
in the url because they want to have it work from javascript/html,
actionscript(flash)/silverlight clients without having to modify headers as
much.

These points are great though and help make better restful apps.

~~~
warfangle
If only someone built a nice, RESTful module for JavaScript, instead of these
crappy (I'm looking at you, primarily, Prototype) AJAX interfaces.

Ponder... something to include in my in-progress library, perhaps?

~~~
labria
Here you go: <http://www.thoughtbot.com/projects/jester>

~~~
warfangle
Unfortunately, that's fairly heavy - and depends on Prototype for a lot of
things (including class creation, etc). Unfortunately, Prototype's handling of
object manipulation is extremely slow, especially when calling a base method:
[http://ajaxian.com/archives/javascript-inheritance-
performan...](http://ajaxian.com/archives/javascript-inheritance-performance)

This is why I'm making this independent of other libraries. Implementing a
nice interface to the mess that is XMLHttpRequest is not that difficult - and
for what should be a tight, lightweight library, requiring something like
Prototype is overkill.

------
mjs
What would a RESTful API for a queue resource look like? I'm thinking of
something that supports push, pop, shift, unshift, etc.

Is there a meaningful difference between:

GET /user/1

GET /search?user=1

GET /?method=search&user=1

Is REST about the URLs you use, or the operations on those URLs, or both?

~~~
bct

        GET /q
    
        200 OK
        { 'start': '/q/start', 'end': '/q/end', 'shift': '/q/shift', 'pop': '/q/pop' }
    
        POST /q/end
        x
    
        200 OK
        Location: /q/some-identifier-for-element-x
    

The queue now contains [x].

    
    
        POST /q/start
        a
    
        200 OK
        Location: /q/some-identifier-for-element-a
    

The queue now contains [a, x].

    
    
        POST /q/pop
        POST /q/shift
    

With obvious results. I'm not totally happy with the last 2 operations,
another solution might be to GET /q/start or /q/end and DELETE the returned
queue element URL. If the delete succeeds, do what you want with the data,
otherwise assume that somebody got to it before you and attempt another GET-
DELETE.

Neither method handles "client never got the server's response" very well, I'm
not sure what a better solution would be.

Totally generic things like this are unusual, you can usually come up with a
better set of resources and operations based on your problem domain.

REST is about the operations on the URLs; the URLs themselves should be
totally opaque.

Without knowing anything about how the 3 urls you gave are used, what other
operations are possible and how they interact with other resources it is
impossible to say whether you're doing REST. The third one looks very
suspicious, however (the second one too, though less so).

------
tybris
OK, so being perfectly RESTful is a pain. Just be RESTful enough.

------
JulianMorrison
Using custom XML is also not very REST. I would write an API in a way that
uses the Accept header to demand either a HTML microformat or JSON, with the
former laid out for web browser use.

~~~
mbreese
Using custom XML is perfectly fine. It may not be the way you'd do it (or me
for that matter), but there is nothing wrong with XML as a representation for
data.

In fact, this is what XML was actually designed for.

~~~
JulianMorrison
XML is fine. Custom is the problem. A browser can't read it and the syntax is
evident only by example.

~~~
gnaritas
Browsers aren't supposed to be able to read it. If someone is spitting out
custom XML, the client is not meant to be a browser, it's meant to be an app
of some sort, or an Ajax client who can read it.

~~~
JulianMorrison
If you're doing REST, browser-readability is good. It allows the API to be
remotely explorable, self-explanatory, something a prospective user can test-
drive with no investment in client code. Plus of course, it's a damn sight
easier to test during development.

~~~
mbreese
See, there's the problem. You're trying to wrap a custom data model around
HTML. HTML should model one thing: HTML documents. Browser-readability should
have nothing to do with a REST API to a web service.

But your browser is attempting to render an XML document, then the server
probably has a MIME content-type error someplace.

I do agree that it is nice to be able to test something pretty easily, but the
browser is probably the wrong thing to use for this. I always end up mocking
up some scripts using curl or just manually typing in commands to the HTTP
server using: telnet hostname 80

~~~
kragen
_See, there's the problem. You're trying to wrap a custom data model around
HTML. HTML should model one thing: HTML documents._

This is like saying, "See, there's the problem. You're trying to express
mathematics with pencil marks. Pencils should write one thing: black marks on
paper."

I don't see how "HTML documents" in any way constrains the semantic range of
the thing being modeled.

