Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I don't understand the benefit to HATEOAS for APIs intended for use by programs (as opposed to humans directly browsing your API). Sure, the customer isn't bound to a URL schema but they are bound to a data schema which is the same thing in my mind.

For example, assume I want to view an item on an order, let's assume I've discovered or know the order URL already.

HATEOAS:

order = get(orderURL);
item = get(order.itemURL[5]);

non-HATEOAS:

order = get(orderURL);
item = get(getItemURL(order,5));

In the first model I have to know the fact that the order object has an itemURL field. In the second model I have to know how to construct an item URL. In both cases I have to "know" something ahead of time so what is HATEOAS actually doing for me?

share|improve this question
1  
get(orderURL); should be telling you the fact that the order object has an itemURL field. –  Yannis Rizos May 18 '12 at 1:32
    
When you write the client application you have to know ahead of time what the field is. –  Pace May 18 '12 at 14:05
    
3  
How is an application supposed to get the item from an order if the application doesn't even know an order has an item? Discovery works for manual browsing but not for automated applications. –  Pace Jun 1 '12 at 17:05
    
The man himself talking about it here: roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven –  Thiago Silva Dec 9 '13 at 21:41
add comment

2 Answers 2

up vote 2 down vote accepted

One difference is that the schema is hopefully a standard, or at least can be reused by others.

For example, let's say you're using the Twitter API and you want to support StatusNet too (or instead). Since they use the same data model as Twitter, if the API follows HATEOAS you now just have to change the main URL. If it doesn't, you now have to change each single URL from the code.

Of course, if you need to change the code to put the service's entry point URL anyway, it might not seem so helpful. It really shines is if that URL is dynamically inserted; for example, if you were building a service like Twillio, which would interact with the user's own API.

share|improve this answer
    
That's an interesting point I hadn't considered. –  Pace May 18 '12 at 14:07
    
@YannisRizos: Hmm, I don't see where I said HATEOAS is a standard. I said the "(data) schema is hopefully a standard". In REST terminology, that would be the media type. –  André Paramés May 18 '12 at 15:57
    
On second read, you're absolutely right. –  Yannis Rizos May 18 '12 at 16:03
add comment
  1. Explorable API: It may sound trivial but do not underestimate the power of an explorable API. The ability to browse around the data makes it a lot easier for the client developers to build a mental model of the API and its data structures.

  2. Inline documentation: The use of URLs as link relations can point client developers to documentation.

  3. Simple client logic: A client that simply follows URLs instead of constructing them itself, should be easier to implement and maintain.

  4. The server takes ownership of URL structures: The use of hypermedia removes the client's hard coded knowledge of the URL structures used by the server.

  5. Off loading content to other services: Hypermedia is necessary when off-loading content to other servers (a CDN for instance).

  6. Versioning with links: Hypermedia helps versioning of APIs.

  7. Multiple implementations of the same service: Hypermedia is a necessity when multiple implementations of the same service exists (and one client needs to access more than one of them).

You can find an in-depth explanation of these bullet points here: http://soabits.blogspot.no/2013/12/selling-benefits-of-hypermedia.html

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.