5 ms·

REST – Epic Semantic Fail

40 points by alpb 14y ago

sabat 14y ago
I'm not so sure the OP's argument is substantive. I don't know whether Roy intended that his architectural style, described in his thesis, to become a loosely defined web service 'protocol', but we're not really making everything up as we go along. A well-implemented REST API is far and away simpler to understand (and easier to use) than a SOAP counterpart.
- alpb 14y ago
  Can you elaborate "a well-implemented REST API is far and away simpler to understand" statement, please? Or do you have some examples or points that may make things clear for me? Thanks in advance.
  - arethuza 14y ago
    From my own experience, a decent RESTful API is perfectly easy to use from the command line using curl. Try that with with a SOAP interface!
    - alpb 14y ago
      Yeah, that's what I was thinking. I am just curious how a proper REST API looks different than Github, Stripe or other startups implemented.
      - fusiongyro 14y ago
        I saw an article a while back advocating that when you hit, say, a search resource, it should return links to the next page, so, if you hit /comments/?name=alpb&perPage=10, you might get: <comments nextPage="/comments/?name=alpb&perPage=10&page=2"> ... </comments> There's so many ways to include results though. One way would be: <comment href="/comments/2398293">Text of comment</comment> You could also do: <comment>/comments/2398293</comment> There's no standard way of getting across what a link is to another resource, or where that information should go. I don't think this is, in practice, a huge deal, because people don't write generic consumers of RESTful APIs. At some point you need to actually know what it is you're trying to do and code for it. On top of that, with RDF or XLink or XPointer and whatnot there probably are standards for doing this kind of thing, but nobody knows them, uses them or follows them.
        davedx 14y ago
        Yup, that's HATEOAS: using hypertext to inform your clients about the state of the application (where they are, and what they can do next from this point).
        fusiongyro 14y ago
        My favorite acronym of all time.
        jalfresi 14y ago
        "There's no standard way of getting across what a link is to another resource, or where that information should go." That doesn't quite mesh with my understanding. Some media types support hyperlinks, like HTML, which describe how links should be included (anchors, forms and link elements). For media types that don't support hyperlinks, such as images, video etc; you can use the HTTP header Link (http://www.w3.org/wiki/LinkHeader http://www.w3.org/wiki/LinkHeader). Both these methods support the relationship attribute allowing you to specify the relationship between resources thus documenting the way clients should interact with such linked hypermedia (e.g. the HTML media type specifies that Link elements with the rel attribute should perform a HTTP GET request to the indicated resource). In the example you gave, you could use a rel attribute like "comment" and link to the comments. RESTful clients could then follow the hyperlinks to the comments, knowing how to interact with them and what to do: <link rel="comment" href="/comments/2398293"/>
        fusiongyro 14y ago
        Right, but unless your resources adhere to some other standard, there's no reason why the downstream consumer would expect to find URLs in certain places or know what to do with them if they were there. Again, I don't see this as a problem, though the OP does.
- wanderr 14y ago
  That's a bit of a false dichotomy though. SOAP is a giant turd, but it's not the only alternative out there. JSON-RPC is just as easy to understand as REST, without all the pedantry.
  - fusiongyro 14y ago
    One advantage of REST, I don't know if it's especially meaningful in this context, is that RPC mechanisms encourage people to think of remote calls as local, but remote calls have a lot more failure modes than local ones do. REST keeps you aware that you're dealing with remote resources the whole time.
  - davedx 14y ago
    Most of us don't worry about pedantry too much. We try to stick to best practices - just like with the rest of development we do - and get on with it.
  - sabat 14y ago
    JSON-RPC is just as easy to understand as REST, without all the pedantry. I hadn't heard of that, but it sounds exciting, partly because it's so self-explanatory.
- deleted 14y ago
  [deleted]
lukev 14y ago
He's got some good points about how people talk about REST and how it's not a protocol. But then there's this: If I want to write a client to communicate with your REST API I’m in a world of pain; there’s no serviceutil I can point at your API to generate me a proxy, instead I have to carefully read your documentation (if it exists) and then lovingly handcraft my client using low level HTTP API calls. I would infinitely rather use a well-documented HTTP+XML/JSON/clojuredata protocol. The thought of code generation based on WSDLs still makes me feel a little ill even though I haven't done it in years.
- deleted 14y ago
  [deleted]
  - deleted 14y ago
    [deleted]
- jeremyjh 14y ago
  Yes I had to go back and check the date to make sure it was not 2005, because that was when we had this argument.
- reinhardt 14y ago
  Is there a consensus on why the SOAP/WSDL business sucks? Is it just a lousy bloated implementation of a potentially good idea or it's the whole idea that's misguided/unrealistic/foolish?
  - mythz 14y ago
    I touch on REST vs SOAP and why SOAP sucks here: http://www.servicestack.net/mythz_blog/?p=154 http://www.servicestack.net/mythz_blog/?p=154 In general I believe the topic of REST encourages elitist attitudes, cargo cults and un-pragmatic solutions, which I also touch on at: http://www.servicestack.net/mythz_blog/?p=665 http://www.servicestack.net/mythz_blog/?p=665 and I still strongly believe message-based solutions promote better designs for SOA-style remote services: https://github.com/ServiceStack/ServiceStack/wiki/Advantages-of-message-based-web-services https://github.com/ServiceStack/ServiceStack/wiki/Advantages...
ori_b 14y ago
His whole argument can be distilled down to "REST isn't a protocol, it's a protocol pattern". True enough, but I'm surprised that this is news to anyone working with REST. Edit: I said "API", should have said "Protocol"
- podperson 14y ago
  Actually I thought his whole argument was down to "REST isn't a protocol the way HTTP is a protocol" -- look the "P" stands for "protocol" -- which (a) is true in some specific technical sense, and (b) isn't important. I quote: "This style has no agreed protocol." and "The core missing pieces of any RESTful web service protocol are agreed standards on media type and link metadata." OK, so what?
  - deno 14y ago
    > OK, so what? Well, when you try to fill in the blanks you get one of these: 1) AtomPub, which is a relatively simple protcol but has very limited application 2) oData/WSDL, which are powerful but complex
ams6110 14y ago
So he wants to turn REST into SOAP? Personally, I'll pass on that. REST is agile. REST is not about a ponderous, verbose, bloated specification for 5 things I want to do an 50 other things I don't need but have to take with it.
- mapgrep 14y ago
  "It seems like I’ve been rubbishing the whole ‘REST’ project. Actually I think the current situation is healthy. Monolithic ‘enterprise’ protocols like SOAP usually end up being a bad idea."
dggrjx 14y ago
This parallels the beliefs of someone I know, who's working on providing an answer to this in a true REST framework, complete with meaningful links, extra metadata, etc. It's a WIP, but I'm sure he'd enjoy the conversation if others are interested. http://www.wrml.org http://www.wrml.org
lttlrck 14y ago
REST's protocol is HTTP. REST isn't an API, but you can create RESTful API's. Yawn. Edit: The first three sentences on the Wikipedia article are all you need to know. http://en.wikipedia.org/wiki/Representational_state_transfer http://en.wikipedia.org/wiki/Representational_state_transfer
- tripa 14y ago
  REST's protocol is not HTTP. Quoting the very page you linked: > REST was initially described in the context of HTTP, but it is not limited to that protocol.
eevilspock 14y ago
Here's what Roy Fielding himself has to say: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... And here's his presentation on the topic: http://www.slideshare.net/royfielding/a-little-rest-and-relaxation http://www.slideshare.net/royfielding/a-little-rest-and-rela... A common REST debate is "When to use POST?". His thoughts on that: http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post
robinhowlett 14y ago
I think it's easier to understand his argument when you think about the problem at scale. Consuming one API is meat and potatoes to most of us; with decent documentation and the REST style largely being followed, API clients can be created rather quickly. However, if I asked you to consume 1000 "REST" APIs, this becomes problematic. There is no agreement on representation, nor is there metadata available to infer commonalities. So what have people done? They've tried to introduce solutions from other "protocols". As mentioned in the article, HAL attempts to introduce a predictable envelope around the data, using links and embedded resources to become so HATEOAS friendly. However, there still are holes. How do I know what to do with links? The rel can tell you only so much - back to the documentation we go. How about we introduce a rel to a schema, like XSD, WADL or JSON Schema? Not many have done that and even fewer enjoy working with them. How about knowing if I can PUT or POST to one of these links? Well the API could support OPTIONS request, but does this suit your data intensive mobile app consuming the API? Not too snappy. We could list them out individually in the representation (thereby replicating the HTTP design through representation) but now the size of the representation is growing dramatically just to support metadata that rarely changes. OData, GData and even CMIS have all tried to take a stab at data communication protocols. Yes, they bring solutions to some of these issues at the cost of complexity and verbosity. Plus, they use use discovery endpoints. And they still tend to fall back on XML over JSON because of use of Atom etc. And now we are halfway back to SOAP. How about the versioning issue? Should client be aware of representation structure changes and adapt accordingly? Well WRML (http://www.wrml.org/ http://www.wrml.org/) tried to take that one on and all the best to you if you read that through once and understand it, never mind implementing the actual clients and servers. As ori_b summarized "REST isn't a protocol, it's a protocol pattern". REST can't fit all scenarios. But I think what's becoming clear is that no-one has found anything better, just more specialized. So the days of auto-building clients to consume APIs is far away. I guess we'll just have to embrace the chaos and keep building snowflakes.
NanoWar 14y ago
So we HAVE the Google Discovery Service [1] that would be awesome if it could be used with other than just google's APIs. [1] https://developers.google.com/discovery/v1/getting_started https://developers.google.com/discovery/v1/getting_started

40 points by alpb 14y ago

sabat 14y ago

I'm not so sure the OP's argument is substantive. I don't know whether Roy intended that his architectural style, described in his thesis, to become a loosely defined web service 'protocol', but we're not really making everything up as we go along. A well-implemented REST API is far and away simpler to understand (and easier to use) than a SOAP counterpart.

alpb 14y ago
Can you elaborate "a well-implemented REST API is far and away simpler to understand" statement, please? Or do you have some examples or points that may make things clear for me? Thanks in advance.
- arethuza 14y ago
  From my own experience, a decent RESTful API is perfectly easy to use from the command line using curl. Try that with with a SOAP interface!
  - alpb 14y ago
    Yeah, that's what I was thinking. I am just curious how a proper REST API looks different than Github, Stripe or other startups implemented.
    - fusiongyro 14y ago
      I saw an article a while back advocating that when you hit, say, a search resource, it should return links to the next page, so, if you hit /comments/?name=alpb&perPage=10, you might get: <comments nextPage="/comments/?name=alpb&perPage=10&page=2"> ... </comments> There's so many ways to include results though. One way would be: <comment href="/comments/2398293">Text of comment</comment> You could also do: <comment>/comments/2398293</comment> There's no standard way of getting across what a link is to another resource, or where that information should go. I don't think this is, in practice, a huge deal, because people don't write generic consumers of RESTful APIs. At some point you need to actually know what it is you're trying to do and code for it. On top of that, with RDF or XLink or XPointer and whatnot there probably are standards for doing this kind of thing, but nobody knows them, uses them or follows them.
      - davedx 14y ago
        Yup, that's HATEOAS: using hypertext to inform your clients about the state of the application (where they are, and what they can do next from this point).
        fusiongyro 14y ago
        My favorite acronym of all time.
      - jalfresi 14y ago
        "There's no standard way of getting across what a link is to another resource, or where that information should go." That doesn't quite mesh with my understanding. Some media types support hyperlinks, like HTML, which describe how links should be included (anchors, forms and link elements). For media types that don't support hyperlinks, such as images, video etc; you can use the HTTP header Link (http://www.w3.org/wiki/LinkHeader http://www.w3.org/wiki/LinkHeader). Both these methods support the relationship attribute allowing you to specify the relationship between resources thus documenting the way clients should interact with such linked hypermedia (e.g. the HTML media type specifies that Link elements with the rel attribute should perform a HTTP GET request to the indicated resource). In the example you gave, you could use a rel attribute like "comment" and link to the comments. RESTful clients could then follow the hyperlinks to the comments, knowing how to interact with them and what to do: <link rel="comment" href="/comments/2398293"/>
        fusiongyro 14y ago
        Right, but unless your resources adhere to some other standard, there's no reason why the downstream consumer would expect to find URLs in certain places or know what to do with them if they were there. Again, I don't see this as a problem, though the OP does.
wanderr 14y ago
That's a bit of a false dichotomy though. SOAP is a giant turd, but it's not the only alternative out there. JSON-RPC is just as easy to understand as REST, without all the pedantry.
- fusiongyro 14y ago
  One advantage of REST, I don't know if it's especially meaningful in this context, is that RPC mechanisms encourage people to think of remote calls as local, but remote calls have a lot more failure modes than local ones do. REST keeps you aware that you're dealing with remote resources the whole time.
- davedx 14y ago
  Most of us don't worry about pedantry too much. We try to stick to best practices - just like with the rest of development we do - and get on with it.
- sabat 14y ago
  JSON-RPC is just as easy to understand as REST, without all the pedantry. I hadn't heard of that, but it sounds exciting, partly because it's so self-explanatory.
deleted 14y ago
[deleted]

lukev 14y ago

He's got some good points about how people talk about REST and how it's not a protocol. But then there's this: If I want to write a client to communicate with your REST API I’m in a world of pain; there’s no serviceutil I can point at your API to generate me a proxy, instead I have to carefully read your documentation (if it exists) and then lovingly handcraft my client using low level HTTP API calls. I would infinitely rather use a well-documented HTTP+XML/JSON/clojuredata protocol. The thought of code generation based on WSDLs still makes me feel a little ill even though I haven't done it in years.

deleted 14y ago
[deleted]
- deleted 14y ago
  [deleted]
jeremyjh 14y ago
Yes I had to go back and check the date to make sure it was not 2005, because that was when we had this argument.
reinhardt 14y ago
Is there a consensus on why the SOAP/WSDL business sucks? Is it just a lousy bloated implementation of a potentially good idea or it's the whole idea that's misguided/unrealistic/foolish?
- mythz 14y ago
  I touch on REST vs SOAP and why SOAP sucks here: http://www.servicestack.net/mythz_blog/?p=154 http://www.servicestack.net/mythz_blog/?p=154 In general I believe the topic of REST encourages elitist attitudes, cargo cults and un-pragmatic solutions, which I also touch on at: http://www.servicestack.net/mythz_blog/?p=665 http://www.servicestack.net/mythz_blog/?p=665 and I still strongly believe message-based solutions promote better designs for SOA-style remote services: https://github.com/ServiceStack/ServiceStack/wiki/Advantages-of-message-based-web-services https://github.com/ServiceStack/ServiceStack/wiki/Advantages...

ori_b 14y ago

His whole argument can be distilled down to "REST isn't a protocol, it's a protocol pattern". True enough, but I'm surprised that this is news to anyone working with REST. Edit: I said "API", should have said "Protocol"

podperson 14y ago
Actually I thought his whole argument was down to "REST isn't a protocol the way HTTP is a protocol" -- look the "P" stands for "protocol" -- which (a) is true in some specific technical sense, and (b) isn't important. I quote: "This style has no agreed protocol." and "The core missing pieces of any RESTful web service protocol are agreed standards on media type and link metadata." OK, so what?
- deno 14y ago
  > OK, so what? Well, when you try to fill in the blanks you get one of these: 1) AtomPub, which is a relatively simple protcol but has very limited application 2) oData/WSDL, which are powerful but complex

ams6110 14y ago

So he wants to turn REST into SOAP? Personally, I'll pass on that. REST is agile. REST is not about a ponderous, verbose, bloated specification for 5 things I want to do an 50 other things I don't need but have to take with it.

mapgrep 14y ago
"It seems like I’ve been rubbishing the whole ‘REST’ project. Actually I think the current situation is healthy. Monolithic ‘enterprise’ protocols like SOAP usually end up being a bad idea."

dggrjx 14y ago

This parallels the beliefs of someone I know, who's working on providing an answer to this in a true REST framework, complete with meaningful links, extra metadata, etc. It's a WIP, but I'm sure he'd enjoy the conversation if others are interested. http://www.wrml.org http://www.wrml.org

lttlrck 14y ago

REST's protocol is HTTP. REST isn't an API, but you can create RESTful API's. Yawn. Edit: The first three sentences on the Wikipedia article are all you need to know. http://en.wikipedia.org/wiki/Representational_state_transfer http://en.wikipedia.org/wiki/Representational_state_transfer

tripa 14y ago
REST's protocol is not HTTP. Quoting the very page you linked: > REST was initially described in the context of HTTP, but it is not limited to that protocol.

eevilspock 14y ago

Here's what Roy Fielding himself has to say: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte... And here's his presentation on the topic: http://www.slideshare.net/royfielding/a-little-rest-and-relaxation http://www.slideshare.net/royfielding/a-little-rest-and-rela... A common REST debate is "When to use POST?". His thoughts on that: http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post http://roy.gbiv.com/untangled/2009/it-is-okay-to-use-post

robinhowlett 14y ago

I think it's easier to understand his argument when you think about the problem at scale. Consuming one API is meat and potatoes to most of us; with decent documentation and the REST style largely being followed, API clients can be created rather quickly. However, if I asked you to consume 1000 "REST" APIs, this becomes problematic. There is no agreement on representation, nor is there metadata available to infer commonalities. So what have people done? They've tried to introduce solutions from other "protocols". As mentioned in the article, HAL attempts to introduce a predictable envelope around the data, using links and embedded resources to become so HATEOAS friendly. However, there still are holes. How do I know what to do with links? The rel can tell you only so much - back to the documentation we go. How about we introduce a rel to a schema, like XSD, WADL or JSON Schema? Not many have done that and even fewer enjoy working with them. How about knowing if I can PUT or POST to one of these links? Well the API could support OPTIONS request, but does this suit your data intensive mobile app consuming the API? Not too snappy. We could list them out individually in the representation (thereby replicating the HTTP design through representation) but now the size of the representation is growing dramatically just to support metadata that rarely changes. OData, GData and even CMIS have all tried to take a stab at data communication protocols. Yes, they bring solutions to some of these issues at the cost of complexity and verbosity. Plus, they use use discovery endpoints. And they still tend to fall back on XML over JSON because of use of Atom etc. And now we are halfway back to SOAP. How about the versioning issue? Should client be aware of representation structure changes and adapt accordingly? Well WRML (http://www.wrml.org/ http://www.wrml.org/) tried to take that one on and all the best to you if you read that through once and understand it, never mind implementing the actual clients and servers. As ori_b summarized "REST isn't a protocol, it's a protocol pattern". REST can't fit all scenarios. But I think what's becoming clear is that no-one has found anything better, just more specialized. So the days of auto-building clients to consume APIs is far away. I guess we'll just have to embrace the chaos and keep building snowflakes.

NanoWar 14y ago

So we HAVE the Google Discovery Service [1] that would be awesome if it could be used with other than just google's APIs. [1] https://developers.google.com/discovery/v1/getting_started https://developers.google.com/discovery/v1/getting_started