5 ms·

REST is good, better than RPC, SOAP... finally people can understand and use APIs easily and happily. The URL /customer/33245/order/8769 is perfect, looks like

by jawb 12y ago

REST is good, better than RPC, SOAP... finally people can understand and use APIs easily and happily. The URL /customer/33245/order/8769 is perfect, looks like a directory path and reflect the relationship between the entities. Arguing about the best url, status code and best verb is the irrelevant part in REST. Why can't people just do whatever it works for the users while respecting the standards when they can ?!

lmm 12y ago
I think you've inadvertently put your figure on the part that really matters. REST is worse than SOAP or something like Thrift for discoverability, worse for ease of use, worse for practically every criterion you could think about. The one thing it does right is being easy to explore with a web browser. So optimize for that. Make it easy for a developer to look at your API with a web browser. This means simple URLs. It may mean a limited form of HATEOAS, in terms of providing links to the next things. But it absolutely doesn't mean using HTTP status codes to convey important information. It doesn't mean using content negotiation for API versioning. It doesn't mean adopting every new HTTP verb, and frankly there's a lot of value in making every endpoint accessible over GET and POST. Those who insist on strict REST are missing why it succeeded.
- dragonwriter 12y ago
  > REST is worse than SOAP or something like Thrift for discoverability How? > worse for ease of use How? > worse for practically every criterion you could think about. I can think of lots of criteria, but very few on which I can see a compelling argument for REST being inferior to SOAP except "degree of support from libraries written to support SOAP".
  - lmm 12y ago
    There's no WSDL or .thrift -equivalent for discovery, and no autogenerated client code which makes use harder. Getting up and running is slower because you have no way to validate that your messages are well-formed short of throwing them at the server and seeing what it sends back. What criteria are you seeing REST as better on?
    - dragonwriter 12y ago
      HATEOAS provides both discovery and, when well-known content types are used, potentially much richer ready-to-use client code than the autogenerated host-language interfaces provided by SOAP and similar protocols.
      - lmm 12y ago
        HATEOAS only lets you discover something by going there, so to speak; it doesn't give you a complete index like a WSDL. At the transport level you get much richer and more structured client code from SOAP. Automated HATEOAS clients are at this point purely theoretical, and anything you could put a content-type on and send over HATEOAS you could equally embed in a SOAP response. If the thing you wanted to embed can be expressed as XML, you can do much better.
        lmorchard 12y ago
        Your browser is an "automated HATEOAS client". You can toss it any old HTML doc and it knows what to do with things described in the HTML content-type spec such as links, forms, images, scripts, etc.
        lmm 12y ago
        No, the browser is very much a manual HATEOAS client.
        jalfresi 12y ago
        Incorrect. When you view a html page, the browser fetches the javascript, css and images in the page automatically.
        dragonwriter 12y ago
        > HATEOAS only lets you discover something by going there, so to speak; it doesn't give you a complete index like a WSDL. HATEOAS doesn't inherently require that you "go" anywhere to get a hypertext document describing an API, and can be as complete as you want. But, since its really designed for web-scale decentralized interlinked APIs, no, its not primarily intended to have one document that gives you every possible linked endpoint. > Automated HATEOAS clients are at this point purely theoretical Googlebot is an example of an automated HATEOAS client that handles a wide array of content types. It is decidedly not purely theoretical.
- jawb 12y ago
  For discoverability , it's a feature not a bug, when i want to use a REST API I can read the docs written for humans not try to find my way in a WSDL. Also a will built REST API is straightforward once you know the entities that you will be manipulating. IMHO the only bad thing about REST is; it's natural for CRUD, but not as easy for non-CRUD apps.
- lerno 12y ago
  If you use the wsdl for discovery, then you are doing something that's rather dangerous as there are no guarantees what that method does or that it is correct -> use documentation instead. If the call is something important (e.g. money transfer) "exploring" rather than knowing is grounds for firing someone.

by jawb 12y ago

lmm 12y ago

I think you've inadvertently put your figure on the part that really matters. REST is worse than SOAP or something like Thrift for discoverability, worse for ease of use, worse for practically every criterion you could think about. The one thing it does right is being easy to explore with a web browser. So optimize for that. Make it easy for a developer to look at your API with a web browser. This means simple URLs. It may mean a limited form of HATEOAS, in terms of providing links to the next things. But it absolutely doesn't mean using HTTP status codes to convey important information. It doesn't mean using content negotiation for API versioning. It doesn't mean adopting every new HTTP verb, and frankly there's a lot of value in making every endpoint accessible over GET and POST. Those who insist on strict REST are missing why it succeeded.

dragonwriter 12y ago
> REST is worse than SOAP or something like Thrift for discoverability How? > worse for ease of use How? > worse for practically every criterion you could think about. I can think of lots of criteria, but very few on which I can see a compelling argument for REST being inferior to SOAP except "degree of support from libraries written to support SOAP".
- lmm 12y ago
  There's no WSDL or .thrift -equivalent for discovery, and no autogenerated client code which makes use harder. Getting up and running is slower because you have no way to validate that your messages are well-formed short of throwing them at the server and seeing what it sends back. What criteria are you seeing REST as better on?
  - dragonwriter 12y ago
    HATEOAS provides both discovery and, when well-known content types are used, potentially much richer ready-to-use client code than the autogenerated host-language interfaces provided by SOAP and similar protocols.
    - lmm 12y ago
      HATEOAS only lets you discover something by going there, so to speak; it doesn't give you a complete index like a WSDL. At the transport level you get much richer and more structured client code from SOAP. Automated HATEOAS clients are at this point purely theoretical, and anything you could put a content-type on and send over HATEOAS you could equally embed in a SOAP response. If the thing you wanted to embed can be expressed as XML, you can do much better.
      - lmorchard 12y ago
        Your browser is an "automated HATEOAS client". You can toss it any old HTML doc and it knows what to do with things described in the HTML content-type spec such as links, forms, images, scripts, etc.
        lmm 12y ago
        No, the browser is very much a manual HATEOAS client.
        jalfresi 12y ago
        Incorrect. When you view a html page, the browser fetches the javascript, css and images in the page automatically.
      - dragonwriter 12y ago
        > HATEOAS only lets you discover something by going there, so to speak; it doesn't give you a complete index like a WSDL. HATEOAS doesn't inherently require that you "go" anywhere to get a hypertext document describing an API, and can be as complete as you want. But, since its really designed for web-scale decentralized interlinked APIs, no, its not primarily intended to have one document that gives you every possible linked endpoint. > Automated HATEOAS clients are at this point purely theoretical Googlebot is an example of an automated HATEOAS client that handles a wide array of content types. It is decidedly not purely theoretical.
jawb 12y ago
For discoverability , it's a feature not a bug, when i want to use a REST API I can read the docs written for humans not try to find my way in a WSDL. Also a will built REST API is straightforward once you know the entities that you will be manipulating. IMHO the only bad thing about REST is; it's natural for CRUD, but not as easy for non-CRUD apps.
lerno 12y ago
If you use the wsdl for discovery, then you are doing something that's rather dangerous as there are no guarantees what that method does or that it is correct -> use documentation instead. If the call is something important (e.g. money transfer) "exploring" rather than knowing is grounds for firing someone.