7 ms·
Your Web Service Might Not Be RESTful If…
- drawkbox 17y agoGood 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 17y agoIf 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 17y agoHere you go: http://www.thoughtbot.com/projects/jester http://www.thoughtbot.com/projects/jester
- warfangle 17y agoUnfortunately, 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-performance http://ajaxian.com/archives/javascript-inheritance-performan... 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.
- JimmyL 17y ago>> 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?
- kqr2 17y agoThis is an interesting blog post on http authentication woes: http://www.artima.com/weblogs/viewpost.jsp?thread=155252 http://www.artima.com/weblogs/viewpost.jsp?thread=155252
- psadauskas 17y agoEvery single one of these concerns can be solved wuth digest auth over javascript: http://www.peej.co.uk/articles/http-auth-with-html-forms.html http://www.peej.co.uk/articles/http-auth-with-html-forms.htm... and http://www.berenddeboer.net/rest/authentication.html http://www.berenddeboer.net/rest/authentication.html
- alexandros 17y agoRESTful 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 17y agohttp://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... 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 17y agoWell, 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.
- codyrobbins 17y agoAt 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 17y agoSorry, 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 17y agohttp://en.wikipedia.org/wiki/Representational_State_Transfer#Implementation http://en.wikipedia.org/wiki/Representational_State_Transfer...
- nbhat 17y agoGeneral problem is not getting the clients to change but get all the clients to change at same time. Or else you will end up hosting multiple versions of webservice. In enterprise setup its really hard as each organization can have different processes to be followed and value proposition for switching to new version of webservice may not be same for each client.
- paul 17y agoFortunately, 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.
- credo 17y agoI agree. For most web services, the REST purity test is unnecessary. My only point of agreement with the author is that web services that aren't RESTful shouldn't describe themselves as RESTful.
- alexandros 17y agoMost APIs are not restful because their designers had more important issues - Would you say the same for most web pages breaking web stanards or is that another matter entirely?
- wheels 17y agoIt's more like using tables instead of CSS -- the only real compliance with web standards here is valid vs. invalid use of HTTP; everything layered on top of that is mostly subjective in the case of REST dogma. In fact, some of the things in this article directly contradict recommendations in O'Reilly's RESTful Web Services.
- alexandros 17y agoFirst author of HTTP 1.1 is Roy Fielding, same guy who defined REST. In fact, http 1.1 was designed largely to make HTTP restful. As such, you'd be surprise how far HTTP goes towards RESTfulness. For instance the spec defines idempotency and satfety of methods. Ergo, servers may produce valid requests and responses but still fail when it comes to being valid http if their internal operation does not conform to the operation semantics. Look up the google web accelerator fiasco to see how things can go terribly wrong.
- 17y ago
- jasonkester 17y agoNice 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 17y agoWell 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 17y agoThat'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.
- DougBTX 17y agoIt's an interesting artefact of the libraries we use that digest authentication is difficult, but you can "just use" SSL.
- tybris 17y agoOK, so being perfectly RESTful is a pain. Just be RESTful enough.
- JulianMorrison 17y agoUsing 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 17y agoUsing 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 17y agoXML is fine. Custom is the problem. A browser can't read it and the syntax is evident only by example.
- gnaritas 17y agoBrowsers 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 17y agoIf 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 17y agoSee, 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
- mjs 17y agoWhat 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 17y agoGET /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).