Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

In simple terms, hypermedia is how people consuming your services discover your system. One of the great things about hypermedia is that it’s dynamic – so the links you provide through hypermedia can change depending upon the state of the resource your system is providing at runtime (this contrasts with traditional SOA where links/endpoints are static). Hypermedia is often forgotten in RESTful systems design, but HATEOS (Hypermedia as the Engine of Application State) is a core component of REST.

Using hypermedia in the field can sometimes be elusive, or daunting. For more background details, read Chapter 6.4: The Role of Hypermedia in SOA with REST. Take, for instance, the user resource in the ubiquitous user admin system. Many RESTful systems support the following:

Your system may support all five of the above actions on the user resource, but access is probably limited. Normal users can probably view themselves, update themselves, and view other people’s information, but probably can’t delete users, list all users or update other users.

So your API, which supports five operations against users, actually only supports those operations in certain circumstances.

This is where hypermedia can make your API easier to understand, and can simplify how your services are consumed.

In a system that does not employ hypermedia, when you GET a specific user you may often serve up some data such as:

However, this does not let us understand immediately what Dave (an admin) can do in relation to the system.

A better representation of viewing a user (using hypermedia) could be:

This shows us that Dave can list all users, delete that user, edit that user, and also view their profile.

For a normal user looking at Fred, a representation could instead be:

Note that as a normal user looking at Fred, there are no admin operations like listing all users, or deleting/updating other users. The only action they can do (in terms of the user administration sub system) is view their own profile.

So by using hypermedia, we are dynamically offering up different operations on our system, depending upon the type of user accessing the service.

We’re enabling discovery of our system, and allowing that dynamically driven information to be driven by our state – we are representing the state of our system and transferring that state through our API.

Where this gets useful is in the consumer end of our API.

Often, websites that use a remote service (whether RESTful or not) know far too much about the inner workings of the service they are using.

You often see code like this:

In this small example, the website knows about a few things it doesn’t need to:

  • The uri to list the users
  • Whether or not a user is an admin
  • Whether or not a user can list other users
  • Whether or not a user can update/delete the user

By using hypermedia though, we can push the responsibility of that knowledge back to the service, and away from the consuming website:

Now obviously, you’re never going to be able to build completely dumb websites that consume RESTful services, and there’s always going to be some knowledge of the API that leaks out into the consumer application. Limiting those if statements, however, is a worthy goal, which pushes knowledge away from your consuming application.

Another trick to building APIs that expose state, is to push the state of fields within your resource representation. This isn’t strictly hypermedia, but borrows from its understanding of how applications should represent themselves.

Take a user representation before:

One thing that is missing from this is any indication of whether the person viewing that user can edit any fields (think a profile update page).

Another representation (for an Admin) could be:

And the representation for a normal user:

So depending upon the type of user, and who they are viewing, the options change.
For example, a normal user cannot edit their role, but for an admin user, the role field is editable, and a list of potential options are given.

This is where APIs get really useful, and start pushing the state of their resources to the client side. By using this kind of pattern, a single client website page can use the same view to render a representation in HTML without having to resort to if/else statements. The logic remains inside the service.

For more details about REST, see the ebooks referenced below.

Safari Books Online has the content you need

REST continues to gain momentum as the best method for building web services, leaving many web architects to consider whether and how to include this approach in their SOA and SOAP-dominated world. Rest in Practice offers a down-to-earth explanation of REST, with techniques and examples that show you how to design and implement integration solutions using the REST architectural style.
The basic rules of REST APIs – “many nouns, few verbs, stick with HTTP” – seem easy, but that simplicity and power require discipline to work smoothly. REST API Design Rulebook provides the next steps for implementing complex REST projects on simple and extensible foundations.
SOA with REST: Principles, Patterns & Constraints for Building Enterprise Solutions with REST is the first comprehensive tutorial and reference for designing and building RESTful services as part of service-oriented solutions and in conjunction with service-oriented architecture (SOA). This book demonstrates that REST is not only a suitable medium for building truly service-oriented solutions, but also that the service-oriented architectural model is a necessary foundation for REST technology architectures to realize their full business potential.

About the author

Ben Keeping is a freelance developer based in the UK. He currently specializes in applications written in .NET and Ruby, using lean and agile techniques. He can be contacted @benkeeping.

Tags: API, HATEOS, Hypermedia, REST, SOA,

Comments are closed.