Home » Enterprise Java » Web Services » HATEOAS » HATEOAS and Hypermedia Aware Services And Clients :REST

5 Flares Twitter 1 Facebook 1 Google+ 3 LinkedIn 0 Email -- Filament.io 5 Flares ×

In this article we discuss HATEOAS (Hypermedia as the Engine of Application State) Rest constraint and some HATEOAS example and HATEOAS Json representations of embedded hypermedia.Jersey currently supports HATEOAS and Spring Rest-hateoas also provides rich support to buiild Hypermedia-Driven RESTful Web Services.

More advanced features on Web Services:

  1. Design Considerations: When Should We Use JSON instead of XML as Data-interchange Format?
  2. JAX-WS Secure Web Services with Signatures and Encryption: WS-Security with Metro and WSIT
  3. Secure Metro JAX-WS UsernameToken Web Service with Signature, Encryption and TLS (SSL)

What is HATEOAS?

HATEOAS (Hypermedia as the Engine of Application State) is the forth constraint of the REST application architecture. It is the last constraint or the fourth REST interface constraint defined in Roy Fielding’s doctoral dissertation. HATEOAS refers to the use of hypermedia in resource representations to help guide clients navigate through a conversation or in other words client interacts with an application entirely through hypermedia provided dynamically by application servers. This allows you to build services that decouple client and server to a great extent. Moreover it allows the services to evolve independently.
As Roy Fielding specified, Restful APIs must be hypertext-driven. In HATEAOS, resource representations include information about next valid states. This may also be the transitions that lead to next valid states. The client transitions through application states by selecting from the links within a representation.

HATEOAS Tutorial and HATEOAS Example

The best way to explain HATEOAS is by thinking in terms of an actual resource. For example take a bank account as a resource. First client issues a GET request to fetch the account. The server describes the set of actions possible on that account.

HATEOAS Example: Get Account

For example, if the account is in good shape customer can perform the following actions on the account:

  1. Deposit Money
  2. Withdraw Money
  3. Transfer Money
  4. Close Account
  5. View Transactions

In the above case server will respond with a representation that has embedded hypermedia.

 HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: 
 
    {
  "account": {
    "account_number": "9999",
    "balance": {
      "currency": "usd",
      "balance": "1100.00"
    },
    "links": [
      {
        "rel": "deposit",
        "href": "/account/9999/deposit"
      },
      {
        "rel": "withdraw",
        "href": "/account/9999/withdraw"
      },
      {
        "rel": "transfer",
        "href": "/account/9999/transfer"
      },
      {
        "rel": "close",
        "href": "/account/9999/close"
      },
      {
        "rel": "view",
        "href": "/account/9999/view"
      }
    ]
  }
}

The account is the textual representation of the account. The “links” element contains a list of links. These links are described with the relation type of “rel” and the “href” attribute pointing to the available action on the account just accessed. The above response contains 4 possible follow-up links to make a deposit, a withdrawal, a transfer or to close the account.

HATEOAS Example:A n Overdrawn Account Response

In this case, if the account is overdrawn you have just two operation possible on the account. Deposit some money or view transactions. See below the Response below

HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: 
{
  "account": {
    "account_number": "5555",
    "balance": {
      "currency": "usd",
      "balance": "-250.00"
    },
    "link": {
      "rel": "deposit",
      "href": "/account/5555/deposit"
    },
      {
        "rel": "view",
        "href": "/account/9999/view"
      }
  }
}

Jersey Support for HATEOAS

JAX-RS currently offers UriBuilder to simplify URI creation but Jersey adds additional annotation-based alternative to implement declarative linking. You need to have the following maven dependencies.

<dependency>
    <groupId>org.glassfish.jersey.ext</groupId>
    <artifactId>jersey-declarative-linking</artifactId>
    <version>2.17</version>
</dependency>
You will also need to add the following dependencies, if your container doesnt already including them.
<dependency>
    <groupId>javax.el</groupId>
    <artifactId>javax.el-api</artifactId>
    <version>2.2.4</version>
</dependency>
<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>javax-el</artifactId>
    <version>2.2.4</version>
</dependency>

See the article Declarative Hyperlinking for more in-depth details.

Spring HATEOAS

Spring HATEOAS is a library of APIs that you can use to build up resource representations, and control how they’re rendered into supported hypermedia formats.
If you are using maven, you need the following maven dependency and any other core spring dependencies to start with Spring HATEOAS.

  <dependency>
            <groupId>org.springframework.hateoas</groupId>
            <artifactId>spring-hateoas</artifactId>
   </dependency>

Read more about Spring HATEOAS.

Restfulie Java

Restfulie Java/Restfulie server side is provided through the VRaptor MVC framework . You also needs to add Restfulie’s jars and add to your classpath to use it at client side.
Read More about Restfulie and Restfulie Java.

Prons of HATEOAS

The HATEOAS constraint decouples client and server. This allows the server functionality to evolve independently. The information about application states leads to less error prone client APIs.
Both human and machines can follow links. Discover-ability is a main advantage.
HATEOAS also ensure consistency since all applications and all parts of the application behave in similar ways.

References

  1. Roy Fielding’s Thesis.
  2. REST APIs must be hypertext-driven
5 Flares Twitter 1 Facebook 1 Google+ 3 LinkedIn 0 Email -- Filament.io 5 Flares ×

About Binu George

Leave a Reply

Your email address will not be published. Required fields are marked *

Paged comment generated by AJAX Comment Page

Google+ Plus Follow on Twitter Like On Facebook Linked Follow

Popular post

JAX-WS Web Services and Clients Java JAX-WS Tutorial: Develop Web Services and Clients (Consumers) Using JAX-WS
jax-ws usernametoken example JAX-WS and Secure Java Web Services using UsernameToken : WS-Security with Metro and WSIT
How to Fix : java.security.cert.CertificateException: No name matching localhost found
JAX-WS exception fault handling example JAX-WS Exceptions and Faults: Annotation, Exception and Fault Handling Examples
SOAP Binding: Difference between Document and RPC Style Web Services

Subscribe to Enterprise Java newsletter
Subscribe
Get Enterprise Java Newsletter

Enter your email and stay on top of things,