We briefly covered this topic in Chapter 1, Introducing the REST Architectural Style, under the Hypermedia as the Engine of Application State (HATEOAS) section. 

Before we get into the details of the JAX-RS and Jersey offerings, let's take a step back to understand the need for HATEOAS APIs. When exposing operations to be performed on an entity via RESTful services, one of the key things that gets undermined is exposing the entity relationships to the consumer of the service. The flow on impact is that the consumer ends up hardcoding the logic in the client application.

Let's take the case of an online shopping cart application. Is it wise to allow the creation of an order without any products added to the basket or any payments done? Autonomously implementing an order, product, or payments entity service without considering the relationship is obviously not a good design. The realization of entity linking while developing RESTful services is made possible using the HATEOAS constraint. Also, this gives a representation of the state of the application, with the choice of the next possible actions based on the state of the entity. Since the next possible actions are commonly represented as the endpoint for a service or link, you must include all the possible links in the API responses when you build a HATEOAS-compliant API.

Please be warned that there is no universally accepted format for representing links between two resources in JSON.  Various API vendors or enterprises use different formats, depending upon the API guidelines that they follow. 

Choosing where to place the links is based on the REST API guidelines that you follow for your application. We will discuss this topic in detail in Chapter 8, RESTful API Design Guidelines.

The link APIs offered by both JAX-RS and Jersey are flexible enough to meet the requirements of many of the common formats.