6 ms·

The one true REST explanation

194 points by jipumarino 16y ago

IgorPartola 16y ago
Are there any good examples out there of services that implement that last level? I have seen and used the others but not discoverability.
- mikek85 16y ago
  http://gowalla.com/api/explorer http://gowalla.com/api/explorer isn't bad edit: Btw, any well designed website is at level 3.
- smeatish 16y ago
  Check out twilio's documentation on their REST API: http://www.twilio.com/docs/api/2010-04-01/rest/response#hypermedia http://www.twilio.com/docs/api/2010-04-01/rest/response#hype... Since their core product is an API, they've done a really good job building in all the levels of REST discussed in the article, including discoverability.
- jchrisa 16y ago
  Any website that uses HTML forms (properly) is at the last level. Also, using the <a href ... > tag is also using HTML as the engine of application state transitions. This article makes things out to be more complicated than they actually are. Just make decent HTML. REST was extracted from the web, it doesn't need to be imposed on it.
tszming 16y ago
This is one of the best (but simple) explanation of REST.
- boucher 16y ago
  Although intended for a different audience, I enjoyed this one when I read it: http://tomayko.com/writings/rest-to-my-wife http://tomayko.com/writings/rest-to-my-wife
- parenthesis 16y ago
  See also http://quandyfactory.com/blog/65/designing_a_restful_web_application http://quandyfactory.com/blog/65/designing_a_restful_web_app... .
joblessjunkie 16y ago
I'm with him until he gets to "Hypermedia Controls", which strikes me as needless bureaucracy. The 'link rel = "royalhope.nhs.uk/linkrels/slot/book"' element isn't really helping anything. Before you can consume that service, you need to know what "royalhope.nhs.uk/linkrels/slot/book" actually means, and if you already know that, then having it listed here in the response justs wastes space. He's disguising a custom verb under a cloak of some sort of 'standardization' which isn't actually part of HTTP or any common web practice. The consumer of this service will need to know what all the verb URIs mean and precisely how to use them anyway, so listing them here doesn't provide any benefit and significantly complicates the communication. In this way, the "Hypermedia Protocol" doesn't demonstrate any edge over old-school XML RPC. Up until that point, I agreed with the article. Simple objects exposed using standard HTTP verbs is the way to go -- but I stop short of supporting random lists of verbs labeled with URIs as just more needless bureaucracy.
- scott_s 16y ago
  I understood it to be decoupling the what from the how. In this case, it decoupled knowing that you needed to book an appointment from the URI that lets you do that. If I already what what I want to do, but I allow a service to tell me how to do it, me and the service have a looser coupling. If the service decides to change how I accomplish the task, then I should seamlessly adapt.
  - stevenwei 16y ago
    But, in practice, how often does a service change an URI only, without changing the input or output parameters (causing you to have to re-factor your client anyway)?
    - drewp 16y ago
      Often merely moving from the dev environment to the release environment changes the URIs. Sure, you could try to minimize the part that changes between environments and teach all your clients to form correct URIs between environments, but it's still coupling. And dev/prod is hardly the only thing people find themselves adjusting in URIs; it was just an example.
mattberg 16y ago
curious: why is the initial resource used to get the list of slots /doctors/mjones/slots?date=20100104&status=open and not /slots?doctor=mjones&date=20100104&status=open? if i am setting up future communications at /slots/1234, to me /slots?doctor=mjones&date=20100104&status=open makes more sense. would you typically just have both resources available at those locations?
- rgoddard 16y ago
  Something like depends on the context of the whole application and how you want to organize it. The first way puts the emphasis on the /doctors/mjones/... If you have other actions related to doctors like /doctors/mjones/contact, this way can provide a more coherent organization. Plus you can extend it to something like /labs/questdiagnostic/mri/slots? So you can decouple the concept of 'slots' from doctor, allowing you to extend it to other types of appointments without having to alter slots. The parameters are the items that are also the most likely to vary. When making an appointment you will check multiple days, but you are much less likely to check multiple doctors. Plus the days are more temporal in nature while the list of doctors is going to stay the same for longer.
buro9 16y ago
This stuff isn't new, it just isn't widely adopted yet. OpenSearch does stuff like this: http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_4 http://www.opensearch.org/Specifications/OpenSearch/1.1/Draf... It describes an interface (Atom XML based) that further self-describes how it was called and what you can do to it (how to search within results, for example). Simply applying that thinking to JSON based RESTful services gives you that question "What can I do with this?", and that makes building the API easier... for everything you serve describe what can be done with it and how you were called. This then totally de-couples the request from the client, the client can send many queries and not care about them, and get back something that encapsulates the state of the request (search terms), the state of the result (search pagination) and the verbs for each entity (what you can do with it). I never would've called this "Hypermedia Controls", I think that's confusing. It's just having your interfaces describe themselves and be discoverable. Coupled with a WADL-style thing (but probably not WADL itself... perhaps JSON such as on the Freebase API: http://code.google.com/p/google-refine/wiki/ReconciliationServiceApi#Service_Metadata http://code.google.com/p/google-refine/wiki/ReconciliationSe... ). Perhaps we all just need a new catchphrase or buzzword though, just to get the wider industry onboard? I'd rather just say that your services should be discoverable, and that means within the results telling us what we can do, in addition to a top level thing to describe which services exist.
contextfree 16y ago
It's always seemed to me that the difficulty with hypermedia controls is not how to have your server expose them, which is straightforward enough, but how to have your client do something useful with them. It basically means writing your client as a state-graph navigating agent, which makes it closer to AI-ish programming (not surprising, since the argument for REST has been that web services should be structured more like the human-browsable web) than the input -> output or interactive event-driven paradigms that most programmers are more conversant with. Yet the books and online evangelism etc. for REST that I've seen don't really address this issue.
terra_t 16y ago
I find it hard to believe that he's built real systems that work. Yes, "decomposing services into multiple components" works well when everything is living in the same address space, but if you want to build fast and reliable systems, minimizing round trips is important. If I didn't have anything better to do and if I liked dealing with idiots, I'd hang my shingle as a high-priced consultant who helps "enterprises" dig their way out of the REST morass. Just last year I managed to speed up an application 100x by switching from REST to POX. In this case, the app was doing thousands of round trips for no good reason other than architectural purity. In the real world, composite operations should be done, more or less, in transactions. For instance, in one user authentication system I've worked on, there are about ten database updates to create a new user. There really ought to be one "createUser" call that creates the user. You could probably get away with not having database transactions if you're talking to the database locally, but in a distributed app on the wider internet, you just can't expect to do ten communications in a row and have it work "reliably enough".
- troygoode 16y ago
  You find it hard to believe that _Martin Fowler_ has built real systems that work? He is a rather well known programmer, author, speaker, and Chief Scientist at ThoughtWorks.
  - gruseom 16y ago
    It's a fact about the industry that most such consultants-authors-speakers don't actually build systems themselves and haven't for a long time. If you want to get prominent at it, telling other people how to build things is itself a full-time job. The contradiction here is unfortunately very real.
    - troygoode 16y ago
      I agree in principle, but not when applied to Martin Fowler. I doubt the guy who literally wrote the book on refactoring did so without any real-world experience. http://refactoring.com/catalog/index.html http://refactoring.com/catalog/index.html
numbakrrunch 16y ago
nice writeup. caucho's "metaprotocol taxonomy" is great further reading, contrasting REST with other common patterns/protocols: http://hessian.caucho.com/doc/metaprotocol-taxonomy.xtp http://hessian.caucho.com/doc/metaprotocol-taxonomy.xtp
plq 16y ago
I kind of expected the XML to disappear in level 3. In its current form, this is a non-standard extension to HTTP.
wyuenho 16y ago
I don't know if he had intended to put the REST zealotry to rest, but Martin Fowler and Roy field seem to be on the same page when it comes to level 2 REST. I submitted this to HN a few weeks ago, I'm posting it here again: http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post I hope these 2 blog posts will just stop people from equating REST to full HTTP.

194 points by jipumarino 16y ago

Are there any good examples out there of services that implement that last level? I have seen and used the others but not discoverability.

mikek85 16y ago
http://gowalla.com/api/explorer http://gowalla.com/api/explorer isn't bad edit: Btw, any well designed website is at level 3.
smeatish 16y ago
Check out twilio's documentation on their REST API: http://www.twilio.com/docs/api/2010-04-01/rest/response#hypermedia http://www.twilio.com/docs/api/2010-04-01/rest/response#hype... Since their core product is an API, they've done a really good job building in all the levels of REST discussed in the article, including discoverability.
jchrisa 16y ago
Any website that uses HTML forms (properly) is at the last level. Also, using the <a href ... > tag is also using HTML as the engine of application state transitions. This article makes things out to be more complicated than they actually are. Just make decent HTML. REST was extracted from the web, it doesn't need to be imposed on it.

tszming 16y ago

This is one of the best (but simple) explanation of REST.

boucher 16y ago
Although intended for a different audience, I enjoyed this one when I read it: http://tomayko.com/writings/rest-to-my-wife http://tomayko.com/writings/rest-to-my-wife
parenthesis 16y ago
See also http://quandyfactory.com/blog/65/designing_a_restful_web_application http://quandyfactory.com/blog/65/designing_a_restful_web_app... .

joblessjunkie 16y ago

I'm with him until he gets to "Hypermedia Controls", which strikes me as needless bureaucracy. The 'link rel = "royalhope.nhs.uk/linkrels/slot/book"' element isn't really helping anything. Before you can consume that service, you need to know what "royalhope.nhs.uk/linkrels/slot/book" actually means, and if you already know that, then having it listed here in the response justs wastes space. He's disguising a custom verb under a cloak of some sort of 'standardization' which isn't actually part of HTTP or any common web practice. The consumer of this service will need to know what all the verb URIs mean and precisely how to use them anyway, so listing them here doesn't provide any benefit and significantly complicates the communication. In this way, the "Hypermedia Protocol" doesn't demonstrate any edge over old-school XML RPC. Up until that point, I agreed with the article. Simple objects exposed using standard HTTP verbs is the way to go -- but I stop short of supporting random lists of verbs labeled with URIs as just more needless bureaucracy.

scott_s 16y ago
I understood it to be decoupling the what from the how. In this case, it decoupled knowing that you needed to book an appointment from the URI that lets you do that. If I already what what I want to do, but I allow a service to tell me how to do it, me and the service have a looser coupling. If the service decides to change how I accomplish the task, then I should seamlessly adapt.
- stevenwei 16y ago
  But, in practice, how often does a service change an URI only, without changing the input or output parameters (causing you to have to re-factor your client anyway)?
  - drewp 16y ago
    Often merely moving from the dev environment to the release environment changes the URIs. Sure, you could try to minimize the part that changes between environments and teach all your clients to form correct URIs between environments, but it's still coupling. And dev/prod is hardly the only thing people find themselves adjusting in URIs; it was just an example.

mattberg 16y ago

curious: why is the initial resource used to get the list of slots /doctors/mjones/slots?date=20100104&status=open and not /slots?doctor=mjones&date=20100104&status=open? if i am setting up future communications at /slots/1234, to me /slots?doctor=mjones&date=20100104&status=open makes more sense. would you typically just have both resources available at those locations?

rgoddard 16y ago
Something like depends on the context of the whole application and how you want to organize it. The first way puts the emphasis on the /doctors/mjones/... If you have other actions related to doctors like /doctors/mjones/contact, this way can provide a more coherent organization. Plus you can extend it to something like /labs/questdiagnostic/mri/slots? So you can decouple the concept of 'slots' from doctor, allowing you to extend it to other types of appointments without having to alter slots. The parameters are the items that are also the most likely to vary. When making an appointment you will check multiple days, but you are much less likely to check multiple doctors. Plus the days are more temporal in nature while the list of doctors is going to stay the same for longer.

buro9 16y ago

This stuff isn't new, it just isn't widely adopted yet. OpenSearch does stuff like this: http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_4 http://www.opensearch.org/Specifications/OpenSearch/1.1/Draf... It describes an interface (Atom XML based) that further self-describes how it was called and what you can do to it (how to search within results, for example). Simply applying that thinking to JSON based RESTful services gives you that question "What can I do with this?", and that makes building the API easier... for everything you serve describe what can be done with it and how you were called. This then totally de-couples the request from the client, the client can send many queries and not care about them, and get back something that encapsulates the state of the request (search terms), the state of the result (search pagination) and the verbs for each entity (what you can do with it). I never would've called this "Hypermedia Controls", I think that's confusing. It's just having your interfaces describe themselves and be discoverable. Coupled with a WADL-style thing (but probably not WADL itself... perhaps JSON such as on the Freebase API: http://code.google.com/p/google-refine/wiki/ReconciliationServiceApi#Service_Metadata http://code.google.com/p/google-refine/wiki/ReconciliationSe... ). Perhaps we all just need a new catchphrase or buzzword though, just to get the wider industry onboard? I'd rather just say that your services should be discoverable, and that means within the results telling us what we can do, in addition to a top level thing to describe which services exist.

contextfree 16y ago

It's always seemed to me that the difficulty with hypermedia controls is not how to have your server expose them, which is straightforward enough, but how to have your client do something useful with them. It basically means writing your client as a state-graph navigating agent, which makes it closer to AI-ish programming (not surprising, since the argument for REST has been that web services should be structured more like the human-browsable web) than the input -> output or interactive event-driven paradigms that most programmers are more conversant with. Yet the books and online evangelism etc. for REST that I've seen don't really address this issue.

terra_t 16y ago

I find it hard to believe that he's built real systems that work. Yes, "decomposing services into multiple components" works well when everything is living in the same address space, but if you want to build fast and reliable systems, minimizing round trips is important. If I didn't have anything better to do and if I liked dealing with idiots, I'd hang my shingle as a high-priced consultant who helps "enterprises" dig their way out of the REST morass. Just last year I managed to speed up an application 100x by switching from REST to POX. In this case, the app was doing thousands of round trips for no good reason other than architectural purity. In the real world, composite operations should be done, more or less, in transactions. For instance, in one user authentication system I've worked on, there are about ten database updates to create a new user. There really ought to be one "createUser" call that creates the user. You could probably get away with not having database transactions if you're talking to the database locally, but in a distributed app on the wider internet, you just can't expect to do ten communications in a row and have it work "reliably enough".

troygoode 16y ago
You find it hard to believe that _Martin Fowler_ has built real systems that work? He is a rather well known programmer, author, speaker, and Chief Scientist at ThoughtWorks.
- gruseom 16y ago
  It's a fact about the industry that most such consultants-authors-speakers don't actually build systems themselves and haven't for a long time. If you want to get prominent at it, telling other people how to build things is itself a full-time job. The contradiction here is unfortunately very real.
  - troygoode 16y ago
    I agree in principle, but not when applied to Martin Fowler. I doubt the guy who literally wrote the book on refactoring did so without any real-world experience. http://refactoring.com/catalog/index.html http://refactoring.com/catalog/index.html

numbakrrunch 16y ago

nice writeup. caucho's "metaprotocol taxonomy" is great further reading, contrasting REST with other common patterns/protocols: http://hessian.caucho.com/doc/metaprotocol-taxonomy.xtp http://hessian.caucho.com/doc/metaprotocol-taxonomy.xtp

plq 16y ago

I kind of expected the XML to disappear in level 3. In its current form, this is a non-standard extension to HTTP.

wyuenho 16y ago

I don't know if he had intended to put the REST zealotry to rest, but Martin Fowler and Roy field seem to be on the same page when it comes to level 2 REST. I submitted this to HN a few weeks ago, I'm posting it here again: http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post I hope these 2 blog posts will just stop people from equating REST to full HTTP.