4 ms·

It's really worth reading the thesis that started it all (http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm http://www.ics.uci.edu/~fielding/pubs/disse

by smoyer 13y ago

It's really worth reading the thesis that started it all (http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) and I also find this HATEOAS article (http://timelessrepo.com/haters-gonna-hateoas http://timelessrepo.com/haters-gonna-hateoas) worthwhile reading, but to answer your question succinctly, here's my short definition: "REST is inter-computer communication structured such that the server doesn't maintain any client state so that neither the duration between requests nor the number of clients impacts the resource usage of the server." It's not quite true, but the architecture has benefits: 1) No need to replicate client sessions in a clustered environment. 2) There's no impact if a client wait hours between requests. 3) Every resource a client uses has a unique location on the network.

steveklabnik 13y ago
"Haters" author here, glad you've found it useful. I will mention that "nobody" is doing this is wrong nowadays. GitHub is one example, and my employer, Balanced is another. Go on, try it: curl https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2lKo/debits \ -H "Accept-Type: application/vnd.api+json;revision=1.1" \ -u ak-test-1sKqYrBZG6WYpHphDAsM7ZXFEmJlAn1GE: \ -d "appears_on_statement_as=Hacker News" \ -d "amount=5000" \ -d "description=A sample charge to show hypermedia controls" This request (with test credentials) charges the card stored at https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2lKo https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2... If you GET that card with the same credentials, you'll find a link in the response that points to how to debit.
- smoyer 13y ago
  Wow ... Nice to meet you Steve! I'm going to bow out of the discussion since there's an expert here.
  - steveklabnik 13y ago
    Pssssh. Don't do that!
- hamburglar 13y ago
  Ok, I read your article about HATEOAS and there is one thing that bothers me about the discoverability aspect. The example of the discoverable "newcomment" action that can be done on the resource has no clear semantics; it's just an anonymous link. You claim that you could arbitrarily change the link and a good client would follow along, but how did a client even know that /entry/newcomment was the way to make a new comment in the first place, let alone after you rename it to /somethingelse/whatever? I assume the examples are just suffering from being oversimplified, because otherwise the whole scheme seems like a huge sham, but I really don't understand how a client is supposed to magically discover the correct endpoint.
  - steveklabnik 13y ago
    HATEOAS isn't the semantic web. You still need a human to translate what exactly "/entry/newcomment" _means_, in the software sense. But once you have a client that understands one specific vocabulary, if you will, you can use the same client for multiple services which speak that vocabulary. As an example, think about RSS: RSS is a standard, built on top of XML, which shares certain structures and link relations. A human builds an RSS reader, which understands the RSS format, and then you can use that reader on any RSS-enabled site. Another example is https://gist.github.com/steveklabnik/2187514 https://gist.github.com/steveklabnik/2187514 , which understands the 'ALPS microblogging' spec. You can use this microblogging client across any compatible server: http://rstat.us http://rstat.us and http://alps-microblog.herokuapp.com/ http://alps-microblog.herokuapp.com/ are two instances.
    - hamburglar 13y ago
      I'm still not clear on how this is possible: "By the same token, we can change the URI in our <link> tag, and a proper client will just automatically follow along. Brilliant!" If your client has a notion of what exactly "/entry/newcomment" _means_, then how is it going to automatically follow along when the link URI changes?
      - steveklabnik 13y ago

by smoyer 13y ago

steveklabnik 13y ago

"Haters" author here, glad you've found it useful. I will mention that "nobody" is doing this is wrong nowadays. GitHub is one example, and my employer, Balanced is another. Go on, try it: curl https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2lKo/debits \ -H "Accept-Type: application/vnd.api+json;revision=1.1" \ -u ak-test-1sKqYrBZG6WYpHphDAsM7ZXFEmJlAn1GE: \ -d "appears_on_statement_as=Hacker News" \ -d "amount=5000" \ -d "description=A sample charge to show hypermedia controls" This request (with test credentials) charges the card stored at https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2lKo https://api.balancedpayments.com/cards/CC4HEsK6eSriG3Cxs2YR2... If you GET that card with the same credentials, you'll find a link in the response that points to how to debit.

smoyer 13y ago
Wow ... Nice to meet you Steve! I'm going to bow out of the discussion since there's an expert here.
- steveklabnik 13y ago
  Pssssh. Don't do that!
hamburglar 13y ago
Ok, I read your article about HATEOAS and there is one thing that bothers me about the discoverability aspect. The example of the discoverable "newcomment" action that can be done on the resource has no clear semantics; it's just an anonymous link. You claim that you could arbitrarily change the link and a good client would follow along, but how did a client even know that /entry/newcomment was the way to make a new comment in the first place, let alone after you rename it to /somethingelse/whatever? I assume the examples are just suffering from being oversimplified, because otherwise the whole scheme seems like a huge sham, but I really don't understand how a client is supposed to magically discover the correct endpoint.
- steveklabnik 13y ago
  HATEOAS isn't the semantic web. You still need a human to translate what exactly "/entry/newcomment" _means_, in the software sense. But once you have a client that understands one specific vocabulary, if you will, you can use the same client for multiple services which speak that vocabulary. As an example, think about RSS: RSS is a standard, built on top of XML, which shares certain structures and link relations. A human builds an RSS reader, which understands the RSS format, and then you can use that reader on any RSS-enabled site. Another example is https://gist.github.com/steveklabnik/2187514 https://gist.github.com/steveklabnik/2187514 , which understands the 'ALPS microblogging' spec. You can use this microblogging client across any compatible server: http://rstat.us http://rstat.us and http://alps-microblog.herokuapp.com/ http://alps-microblog.herokuapp.com/ are two instances.
  - hamburglar 13y ago
    I'm still not clear on how this is possible: "By the same token, we can change the URI in our <link> tag, and a proper client will just automatically follow along. Brilliant!" If your client has a notion of what exactly "/entry/newcomment" _means_, then how is it going to automatically follow along when the link URI changes?
    - steveklabnik 13y ago