RFC 5988 offers a framework for building links that define the relation between resources on the web. Although this specification defines the properties for the links, it does not define how the links as a whole should be represented in an HTTP message. However, it defines the guidelines for specifying the Link HTTP header. The syntax set for links in the HTTP headers in this specification may supplement the JSON resources as well. Each link in RFC 5988 may contain the following properties:

• Target URI: Each link should contain a target Internationalized Resource Identifier (IRI). This property is represented by the href attribute. In case you are not familiar with IRIs, they are not the same as URIs in a function. However, IRIs extend upon URIs by using the universal character set, whereas URIs are limited to ASCII characters.
• Link relation type: The link relation type describes how the current context (source) is related to the target resource. This is represented by the rel attribute.
• Attributes for target IRI: The attributes for a link include hreflang, media, title, title*, and type, as well as any extension link parameters.

You can learn more about RFC 5988 (web linking) at http://tools.ietf.org/html/rfc5988.

The following example demonstrates how you can use the Link entity-header fields for describing a relationship between two resources. This example defines the relation between the department (identified by id=10) and the employee resources:

GET /departments/10 HTTP/1.1 
Host: packtpub.com 
Accept: application/json 
 
HTTP/1.1 200 OK 
Content-Type: application/json 
Link: <http://www.packtpub.com/departments/10>; rel="self"; 
   type="application/json"; title="Self Link"Link: <http://www.packtpub.com/departments/10/employees>; 
   rel="employees"; type="application/json"; title="Employees"Link: <http://www.packtpub.com/employees/1700>; rel="manager"; 
   type="application/json"; title="Manager" 
{"departmentId": 10, "departmentName": "Administration", 
  "locationId": 1700} 

Note that the syntax set for links in the HTTP headers can also be leveraged for adding the entity links within the resource body. For example, the department response entity in the preceding example can be modified to include the entity links as follows:

{ 
  "departmentId": 10, 
  "departmentName": "Administration", 
  "locationId": 1700 
  "links": { 
    { "rel"="self", "href": "/departments/10", 
      type="application/json" }, 
    { "rel"="employees", "href": "/departments/10/employees",  
      type="application/json" }, 
    { "rel"="manager","href": "/employees/1700",  
      type="application/json" } 
  } 
} 

A detailed discussion on resource link formats falls outside the scope of this book. However, the short but fruitful discussion that we had on HAL and RFC 5988 will definitely help you quickly learn any other resource linking schemes. Here is a quick summary of a few other formats available today for formatting resource links:

• Collection + JSON: This format is a JSON-based hypermedia type for describing a collection of resources represented in JSON. You can learn more about this type at http://amundsen.com/media-types/collection/format.
• JSON Schema: This format is a JSON-based format for defining the structure of the JSON data. As part of this definition, it provides a method for extracting the link relations from one resource to another. To learn more about JSON Schema, go to http://tools.ietf.org/html/draft-zyp-json-schema-04.
• JSON for Linking Data (JSON-LD): This format is a lightweight linked data format. To learn more about JSON-LD, go to http://json-ld.org/.

Although RFC 5988 standardizes the syntax for the Link headers to link web resources, many API vendors do not prefer using the Link headers for linking resources. One of the reasons for not using the Link header is because this approach does not really work when the API returns the collection of resources. This is due to the fact that it is not easy for a client to accurately identify the Link header for a specific resource item present in the collection. Many API vendors prefer to place the links in the entity body as it is more convenient for a client to process. Note that there is no clear consensus among various resource linking schemes that we have today on how the links should be formatted within resource representations. You can choose a format that meets your requirements and stick to it. Also, you may want to document all the APIs clearly, indicating the type of format used for generating the resource links, which will help your API consumers.

Once you decide on the format for representing hypermedia links, the next step is to choose the right tool for implementing it in the application. Here is a quick summary of the JAX-RS and Jersey framework offerings for generating the HTTP links for your REST resource representations:

• javax.ws.rs.core.Link: You can use the Link utility class offered by JAX-RS for generating the HTTP links (based on RFC 5988)
• @org.glassfish.jersey.linking.InjectLink: The @InjectLink annotation can be applied on the resource entity class fields to declaratively generate the HTTP links linking the web resources

To learn how to use the javax.ws.rs.core.Link and org.glassfish.jersey.linking.InjectLink APIs for generating resource links, refer to the Building Hypermedia as the Engine of Application State (HATEOAS) APIs section in Chapter 5, Introducing JAX-RS Implementation Framework Extensions.