Hot answers tagged

49

I think your instincts are largely correct; those proclaimed benefits really aren't all that great, as for any non-trivial web application the clients are going to have to care about the semantics of what they're doing as well as the syntax. But that doesn't mean that you shouldn't make your application follow the principles of HATEOAS! What does HATEOAS ...


24

the app we are building won't simply look at the links and then by itself render the correct UI and make the right ajax calls In fact, this is exactly what HATEOAS will give the UI. Not what is possible, but when it is possible. A formal HATEOAS like HAL, as the question states, gives links that indicate what is possible. But when those links show up ...


15

AFAIK Fielding didn't claim REST was any good, he was just describing the de-facto architecture of the web. That undersells it a bit, I would think. REST is, after all, an enumeration of the architectural style that Fielding was using as chief architect of the HTTP/1.1 spec. But is there actually any reason to think REST is a desirable architecture for ...


10

If you want to understand REST, or HATEOAS, you should probably start by understanding the web. HAL is (effectively) just a substitute for HTML; if you understand how HTML "works", then understanding HAL's role is much easier. What is the "Engine of Application State" referring to? Chapter 5 of Fielding's Thesis. REST is defined by ...


9

The need for discoverability may not be relevant, but the links that allow discoverability serve more purposes. The most important of these, to my mind, is that providing full URI's in the responses to the client, means that no client will ever need to "compose" an URI. That means that no client will ever need knowledge about how the URI's are structured. ...


9

A web application, RESTful or not, is generally not simply a data service; it exposes various resources and provides some behavior, and so it has state; a distinction is made between resource state (client-independent, managed by the application), and application state, which is client-specific. A stateless application doesn't store (client-specific) ...


7

I had the pleasure a while ago to work with an API that had documentation that was very, very hard to understand. Once I managed to get an actual reply from the server, it was possible to compare the documentation with the server reply and use that to decipher the documentation (and yes, deciphering it was the right term). The problem was that if a request ...


7

"Clients" may not be advanced enough to make use of it, but the users of clients can. A client can be something as simple as a web browser, after all. The discoverability is all about enabling people to learn and use the API. For example, Jenkins (the CI server) has a REST-like interface. Go to any page, postfix the URL with "/api", and you get a page ...


6

No, 'full REST' is not that great. As evidenced by the lack of people who implement HATEOS in thier APIs and the endless arguments over which HTTP verb to use for a particular call. But you have to recognise why REST is so popular. Prior to its adoption there were various crazy complicated protocols such as ebXML and SOAP involving acknowledgements, ...


6

The things is, HATEOAS must come with a second pillar that define what a RESTful API is : standardized media type. Roy fielding himself said A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources". With a standardized media type that define the transition explicitely, and hypertext to ...


5

NOTE: I'm no expert on the subject, but I went through a similar process of trying to reconcile the different nuances of people's interpretations of "REST" a few years ago, and this is the takeaway I got from looking into it at the time. To my understanding, this stems from Roy Fielding's Hypermedia as the Engine of Application State aka "HATEOAS", which ...


5

The self link is also used for embedded entities where it can be used to navigate to the proper entity. See this HAL example: { "_links": { "self": { "href": "/orders" }, "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }], "next": { "href": "/orders?page=2" }, "ea:find": { ...


5

I highly recommend that, when using hypermedia, you use a hypermedia enabled media type. There are many JSON based media types out there that support form-like interactions. Here is an example using JSON Hyper-Schema. It behaves just like an HTML Form with method="get". /product HTTP/1.1 200 OK Content-Type: application/json Link: </schema/product-list&...


5

You just include the complete absolute url in an e-mail. That is an entry point to your app. It's a fantastic example of HATEOAS, because it allows an unknown application (email client) to continue a workflow that began in your application, essentially carrying state of that interaction through time and space across unknown boundaries back home to your app. ...


4

You can publish details on your services through a "WADL" http://en.wikipedia.org/wiki/Web_Application_Description_Language It's optional and not every backend REST technos supports this. Jersey, the "official" java implementation of jax-rs, supports it for example - it can be automaitcally generated for you. It's quite rare though, to see it used. I ...


4

The benefits of HATEOAS (Hypermedia) are real for both internal and external APIs. However, the tooling is often lacking to take advantage of those benefits. Let's start with the "problem" of having the make multiple requests to the server. There are several solutions. First of all, if the front-end consistently has to make multiple requests to get what it ...


4

JSON Hyper-Schema is great for this kind of thing. It allows you to define a JSON Schema for the JSON you expect from the request. GET /my-resource/10 HTTP/1.1 200 OK Content-Type: application/json Link: </schema/my-resource>; rel="describedby" { "id": 10, "name": "First object", "status": "new", "manager_id": 200 } GET /schema/my-resource ...


4

What are the advantages of HATEOS compliant RESTful service? In short: You stay in control of your server side, minimize client knowledge about server internals. Imagine Amazon giving you a product page with just the product data, no links or forms to buy the item. It would assume, that you will go to a separate service (let's say a shopping cart service) ...


4

How should REST resources relate to the server database schema? Not at all. The REST architectural principles are completely independent of the technology that is used to persist information. It is entirely possible to create a REST API without any database behind it (and that is exactly what a webserver serving static pages does). However, Roy has also ...


3

As I currently understand HATEOAS is basically all about sending together with each response links with information about what to do next HATEOAS is a lot more than just links. It is "hyper media" as the engine of application state. What is missed in your description is the content type, the formal definition of the hyper media that is passed between ...


3

what is expected to live at the endpoint represented by that URI? A resource of some kind. Generally, you can identify the type of resource by examining the mime type. Often, it's just a web page. How is http://schema.org/name less ambiguous than name? It lives specifically at the http://schema.org/ domain, and the domain itself is unique. In other ...


3

REST is designed to facilitate API stability and reusability over a very long time horizon when you have multiple clients outside of your control. It sounds like your project has a single API client under your control. That being the case, it's very reasonable to tailor your feature set to the needs and wants of that one client. Just make sure the ...


3

This seems like a purely implementation question, it makes no difference to the end result but might make it easier to debug How would you explain to a client that sometimes a call returns X and sometimes Y? How would the client know which type to deserialise to? how would an application using the client know the return type of its call? It wouldnt be ...


2

There are some Hypermedia formats which endeavour to provide richer responses which include more information about what kind of requests to send, and there's nothing stopping you from enriching the response with even more information. Here's an example Siren document: { "class": [ "order" ], "properties": { "orderNumber": 42, "itemCount": ...


2

The whole point is that the client doesn't know anything about the details other than the entry point. Instead of baking the API into the client, the client fetches the document at the entry point, and uses the types of the returned resources to navigate through the results. With a website, the browser already does this, and the only part that is different ...


2

You don't have to build a dynamically generated interface. Though it could be nice it's not required. If you cannot build a dynamic interface just use the links and you are done. Disadvantage is that you are again hard linked to the backend and will crash if something changes. Using the dynamic layout can be quite simple btw: links.forEach(function(link) { ...


2

As @Bart van Ingen Schenau said if your permissions can be mapped to http verbs, you could use the Allow header to indicate which operations are allowed on a resource. But since you talked about the use case of deciding wether or not to render buttons (like edit, delete etc...), you'll find that the Allow header is not enough for collections. That is if you ...


2

In Fielding's presentation on Adobe Experience Manager: REST is NOT an architecture! Rest is an architectural style, which is abstraction of different architecture that exists on the internet. REST is an accumulation of design constraints to induce architectural properties REST is a buzzword, and everyone wants to have RESTful API. In reality, when ...


2

It is to note that Roy was not the original inventor of most of the principles of REST, he puts together many principles that are known to work in previous systems to solve various specific problems. REST is simply the natural conclusion of applying these principles in a single architecture. Even before Roy Fielding wrote his dissertation on REST, the HTTP ...


Only top voted, non community-wiki answers of a minimum length are eligible