Hacker News Reader

Comment by davedx | Hacker News Reader

Dramatic, and makes broad unsubstantiated claims about API's "in the wild", but the details are right. His most important point that we as API writers can work on is the "discovery" part. Hardly anyone is doing HATEOAS [1]. I think the reason for this is that if you write a public API, you're going to document it well (or nobody will use it), and good documentation kind of alleviates the need for in-service discovery.

[1] http://en.wikipedia.org/wiki/HATEOAS

View on HN

I still don't see the value proposition for HATEOAS. Writing a client that can use an API that it doesn't understand seems impossible, so I can't see how discovery is ever going to work. To my mind HATEOAS represents the very complex over-engineering that REST was originally a reaction against.

I only recently properly grokked this. Discovery isn't necessarily the point, although it's nice. What makes HATEOAS essential for me is that if you start with the assumption of HATEOAS, you can add functionality in the form of new links at the server side without breaking existing clients. Yes, there are other ways to achieve this, but HATEOAS is an excellent way of getting it for free.

You can add new functionality by adding new endpoints without using HATEOAS too. The only difference is that it's documented out of band, which incidentally, is primarily a discovery-related concern.

Exactly. It's not just the existence of the endpoints, though. It's also having developed the client from the first release to be HATEOAS-aware which makes the whole thing interesting. If you do that you'll have conventions in the client code which, even if you're not doing automated discovery, will make it easier to add functionality to a new release.

Write most client code in a generic way so that it's easy to add new actions? Sure.

Write the client to use new actions without needing an update? Impossible.

Output the list of available actions using <link rel="..."> rather than some domain-specific tag? What do I ever gain from this other than bloating my API and making it harder to read?

In some cases, client code could be written so that new actions can be discovered and utilised without any changes to the client code. There have been many cases when I've written code that renders things, and I've reused that code to render multiple different things. Eg I might have a page that lists blog posts, and another page that lists comments on a blog post. Some of those things can be deleted, some of them can't, but the code to delete is there for both of them, it's just that on the ones that can't, the delete button is hidden. Using HATEOUS, if the server did start supporting deleting something, that could automatically detect that, and automatically support that new feature that the server now supports.

Sure, use a domain-specific tag. As long as it contains an href, you're still doing HATEOAS.

In service discovery is just convenient. With SOAP libraries, using a web service is as easy as 2-3 lines of code. The library handles loading the wsdl file, generating functions with appropriate parameters, sending requests and parsing response and exception handling. Without this ability, it's a lot more code.

It's not necessarily harder, but it's more code nevertheless.

The problem with SOAP + WDSL was just that it was overly complex and, in my experience, never worked cross-platform & cross-language. And since it was so complex it was "¤%& impossible to debug at lower levels. Argh! I hate soap with such a vengeance it's actually embarrassing.

Agreed. These problems (complex tooling, poor interop, non-human readable WSDL) were my motivation for writing Barrister RPC (a JSON-RPC implementation with a human readable IDL).

For those who find value in separating interface from implementation, you might take a gander.

http://barrister.bitmechanic.com/

True. Once you have the right libraries in place working with SOAP can be surprisingly easy. I always find defining and passing data types/structures the most frustrating exercise with SOAP though, especially collections. REST makes that stuff so much easier.

Reply on news.ycombinator.com