How is Hypermedia to be consumed by the client in a REST architecture?

hateoas
rest api
what is rest
rest specification
rest api example
restful api
rest api concepts
rest api tutorial

In learning about REST architecture, I've noticed that Hypermedia seems to be an important part of the uniform interface constraint to become RESTful; however, I'm having a hard time understanding how this concept of hypermedia is to be consumed by a client based off of the definition of hypermedia found across the web.

From what I understand about REST, hypermedia is/are basically the links that are provided to a client in a rest response containing the representation of a resource (so that the client only has to know about the base entry point url to a REST service). The links are essentially there to help the client know what options it has regarding the representation it received (for example, if I request the /children/ resource, I might receive an xml list of children that also contains links to /children/youngest, /children/oldest/, children/create, etc... This is exactly what i have a hard time understanding... Why does the server have to return these "hypermedia" links to the client? Shouldn't the client have already known about those links? The client isn't going to read the links on its own and follow them correctly... Somebody has to write client code (html and/or javascript for example) beforehand. What good do these links do for the client if the client should have already known about them? What am i missing?

Hypermedia is indeed an important part of creating RESTful interfaces. However, I see a full hypermedia client (sometimes referred to as HATEOAS) as just a point on the spectrum of becoming more RESTful. The Richardson Maturity Model describes 3 steps to becoming more RESTful and I've found these as good guidelines when considering how much of a RESTful patten to adopt on particular projects.

IMO, the best example of a full hypermedia client is a web browser. The web browser understands that the html <a href> tag represents a link. The key to a link is that a user can discover functionality as they move through their journey. So, when designing a RESTful API, the same principle can be applied.

Why does the server have to return these "hypermedia" links to the client?

So, one reason is that clients (if written to expose links) can allow state transitions to be discoverable.

Another benefit to using links is your API becomes responsible for the structure and data of each link. So, the server-side API is generating the links for each request. This means that the server API can make changes (version or structure) to the links without breaking the client.

You can build a RESTful API without links (Richardson Level 2), but then what if you want to change the URL for one of your API requests? You need to either implement a versioning strategy (through the url or headers) or you need to create a new url for the new feature. Through time, this can get out of hand.

Design of a Hypermedia REST API Server and Consuming Client, REST and hypermedia has a lot of benefits but they significantly complicates building both the client and the server API, thus useful only in� TL:DR: This is the first of a two-articles series showing how to build client-server systems by actually applying the REST architecture principles. In this part, you will learn how to create a RESTful API by implementing a simple dashboard wrapper for the Auth0 Management API.

Think about how browsing a web-page works. REST is very similar (although you're actually describing a related topic HATEOAS). The intent is that your client will retrieve the initial data, then have some way of deciding whether or not to request the referenced data. In a browser, some references (such as css, javascript, images) are immediately requested, and others, such as hrefs, are simply displayed to the user, and only retrieved if the user chooses to click the link. The same is true of your REST client -- you will decide for yourself, based on your requirements, which references to automatically request, and which to display to a user for decision making.

If you have an app that shows a person, along with their address, then your app would be written to automatically find the address reference in the person data and retrieve it. If your app shows a person and an option to show related data, then you'd show the person along with hyperlinks (or something similar) that allows the user to choose to retrieve and display the address data.

The issue really comes when you think about how the client visually represents the information it is retrieving. For this, the REST style suggests that you should allow the server to return javascript to dynamically parse the new data (for example, the address in my example above). Maybe the returned data also contains css-like references that will help. Maybe it'll contain javascript links to allow dynamic user interaction (which sounds dangerous to me, but what the hell, it works for the web).

REST Architecture - Part 2: Building the Client, The typical approach to implement a client consuming RESTful or able to handle the resources sent by a RESTful API, including hypermedia,� One of the constraints defined for the architectural style known as REST is "hypermedia as the engine of application state". Mark Baker, well-known for being one of the first who advocated the

Fielding defined the uniform interface constraint in order to decouple the clients from the implementation of the service. This is just the same as defining a new interface in any oo language. You define it to decouple a class from the implementation of its dependency.

To decouple the client from the URI structure you need links in the response, which contain semantic annotation and the URI. So your client can decide which link to follow based on the semantic annotation (e.g. link relation or a term in a related RDF vocab). This way it does not need to know anything about the URI structure.

You need to decouple clients from the implementation details of the services to make them reusable. At the end you can create general clients like a web browsers today. The difference that these clients will understand what they do, so they won't necessary rely on humans.

HATEOAS Driven REST APIs, REST architectural style lets us use the hypermedia links in the response contents. It allows the client can dynamically navigate to the appropriate resources by� REST API Constraints. An API interface is said to be RESTful if it fulfills the following constraints: Uniform Interface: It means, irrespective of any client we are using, the basic concept of implementing and using the REST services will remain the same.

What good do these links do for the client if the client should have already known about them?

They make state transitions more directly a part of the interface. They tell the client whether these links or state transitions are available to be used (or not if they are not present!) in the current state.

If the client did not take notice of this, it could potentially still try to generate and follow an URL for an option (state transition) that was actually not available. It might be necessary to replicate the logic to determine what is possible in a particular state on both sides to be sure to avoid this.

If an invalid link/state transition is attempted, the server should report back an error.

On the other hand, if the client never allowed generating/following a link not provided by the server, it could have awareness and provide feedback about the problem earlier (normally resulting in a clearer situation or error message), and while the server should handle the invalid request correctly, in case it didn't it would be less of a problem as it is much less likely to happen in the first place.

4. Hypermedia - RESTful Web APIs [Book], Like REST, hypermedia isn't a single technology described by a standards Hypermedia is a way for the server to tell the client what HTTP requests the client If you're trying to consume an API like this, you won't get very far dogmatically� HATEOAS (Hypermedia as the Engine of Application State) is a constraint of the REST application architecture that keeps the RESTful style architecture unique from most other network application architectures. The term “hypermedia” refers to any content that contains links to other forms of media such as images, movies, and text.

Something like this.

        var discountDetails = new AddDiscountForm()
        {
            promotionId = 123456,
            discountType = "Promotion",
            discount = UnitValue.FromFloat(14.00)
        };

        await journey
            .SelectRoot()
            .SelectRelation("product-finder", new { barcode = "23409-23097" })
            .SelectItem(0)
            .SelectRelation("add-discount", discountDetails)
            .RunAsync();

In fact I took the idea from my response and built it.

https://github.com/lukepuplett/surfdude-csharp

What is Hypermedia?, As software architect Irakli Nadareishvili explains, “Hypermedia is the matter of which And these days, the term is most often used in the context of developing and client-server-independencies that define REST constraints more carefully � CHAPTER 3 Network-based Architectural Styles. This chapter presents a survey of common architectural styles for network-based application software within a classification framework that evaluates each style according to the architectural properties it would induce if applied to an architecture for a prototypical network-based hypermedia system.

Is REST and HATEOAS a good architecture for web services , The REST interface is designed to be efficient for large-grain hypermedia data transfer When a single organization controls both the client and the server, the that REST are designed to solve, aren't consumed by multiple organizations that� The REST allows us to use a layered system architecture where we deploy the APIs in server A, and store data on server B and authenticate requests in server C., For example, a client cannot simply tell whether he is connected directly to the server or to an intermediary server on the way.

Decoupling the Client and Server with Hypermedia, This is part two in a series about hypermedia and REST. of the formal definition of the REST architectural style and where hypermedia fits As you go up the levels, more of the formal definition of REST is taken into account. Because you might not be able to force client applications or services to upgrade immediately to the new version, a service must support older versions of the API for some period. If you're using an HTTP-based mechanism such as REST, one approach is to embed the API version number in the URL or into an HTTP header.

REST and Hypermedia in 2019, Building a REST API in HTTP usually means deferring to existing their paradigm or implementation of choice, so that should be taken out of consideration. If a response is cacheable, then a client cache is given the right to� In my last post, I argued for designing RESTful hypermedia around the capabilities and needs of the client rather than around a specific service.A reasonable question to ask is whether the constraints of REST require this, or whether it is simply a good practice.

Comments
  • Davin, let's say I am a third-party company that has a simple HTTP accessible api that provides you with the current temperature for your city. You're a mobile app developer who wants to use my endpoint /temperature/Boston. Two questions with this scenario: 1) is my endpoint a "REST" endpoint or even close to it and if so 2)What links would I return to you in the representation of the temperature? Or would there not be any? If there were, how would you use them in your mobile app?
  • 1) if you follow RESTful principles for designing the URL and use the appropriate HTTP verbs you could call it RESTful. 2) How about a link to tomorrow's forecast, or next week's? Or whatever other information (like barometric pressure or wind velocity).
  • If you have a simple service, accessed through GET, that given a specific url (say: myweather.com/temperature/f/boston), always gives the current temperature for Boston, then you basically have a REST service.
  • Any good example to understand client development with jQuery or AngularJS?
  • I can see how this whole link (hypermedia) thing makes sense if you are returning entire html pages to the client -- it makes sense that you could use the provided links to guide the user from page to page and to perform additional functionality on representations. But what if you're just returning xml/json with specific information like weather for your client to display on the top right corner of their page? Do i need to consider hypermedia in this case?
  • Maybe. On my android phone I can see the weather displayed, but if I click it I get more information, and if I click that I get sent to the weather provider's page for full details. If you wanted that behavior then you should return not only the current weather details, but also a link to a more detailed weather report, and within that a link to your homepage with the location parameters in the url.