Hacker News Reader

Comment by lmm | Hacker News Reader

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.

View on HN

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.

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.

> 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".

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?

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.

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.

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.

No, the browser is very much a manual HATEOAS client.

Incorrect. When you view a html page, the browser fetches the javascript, css and images in the page automatically.

> 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.

Googlebot is not an automated HATEOAS client, it's solely an automated web client. Even if the web conformed to all the specifications it would still be an exceedingly atypical example of a HATEOAS API. And googlebot is nowhere near the reliability level that we would require for most use cases.

> Even if the web conformed to all the specifications it would still be an exceedingly atypical example of a HATEOAS API.

The HTTP-powered Web is the prototypical REST (including the HATEOAS constraint that is part of the definintion of REST) API.

Then REST is a wrong word, one that doesn't point to a natural empirical cluster. The web is very different from all the other things that are called "REST API"s.

Most, but not all, "REST" APIs (other than the web) violate at least one element of the definition of REST, most commonly they don't actually implement HATEOAS, requiring out of band knowledge of applicable resource URIs or URI patterns and/or information about data formats not communicated by documentation of media types and hypertext relations.

But that's because REST is often used as a buzzword by people who don't know what the architectural style entails, or aspirationally to describe one goal of the design of an API, but one that may be compromised for conflicting goals.

It's not 'discovery' in the sense that you can't discover an url, change an id here and there and build an url for another product. You don't get endpoints for operations, you get operations that are valid only for that particular product and only for that particular state.

Reply on news.ycombinator.com