Hypermedia embeds links, relationships, and sometimes operations in API representations, allowing consumers to discover related resources and available actions at runtime instead of guessing paths or capabilities. section 11.1.2 section 11.4
Discovering a transfer action
A banking-style transfer representation can link to its source account and expose a cancel action. HAL places relations in _links; Siren can add an actions entry such as cancel with DELETE and a target URL. A consumer follows the returned links rather than constructing /accounts/{source} or assuming cancellation is available. section 11.4 section 11.4.3
Common design choices include:
- Use OPTIONS to discover methods supported by a resource and Link headers to advertise pagination, formats, and other resource links. section 11.4
- Choose a standardized format such as HAL, JSON:API, Siren, or JSON-LD; HAL keeps ordinary JSON data and adds _links, while Siren also describes actions. section 11.4.3
- Offer hypermedia alongside plain JSON through content negotiation, using media types such as application/hal+json or application/vnd.siren+json. section 11.4.4
- Keep essential subject-matter data in the ordinary representation: metadata may describe deletion, but a crucial cancellable flag should remain in the transfer data. section 11.4.5
Hypermedia can simplify generic, dynamic, or AI-powered clients and make API changes easier because consumers follow provider-supplied paths. It adds complexity, however, and is worth adopting only when consumers and compatible client and server libraries can use it. section 11.4.6
Figure 11.5 HAL and Siren propose standardized representations of links between resources. Siren adds the description of possible actions and separates original data and hypermedia metadata.
Compare how HAL and Siren represent resource links; inspect how Siren separates data from hypermedia metadata and adds possible actions. section 11.4.3
