[ADP-322] Hypermedia Alternatives

Guidance

• SHOULD consider alternatives to HAL (Hypertext Application Language) for structuring hypermedia responses, as HAL may not be suitable for all applications and can complicate JSON structures.
• SHOULD explore alternatives such as using the standard HTTP header Link to replace links in hypermedia.
• Instead of using Hypermedia's embed, it is recommended to embed related resources according to [ADP-360].
• If Hypermedia is deemed necessary for your API design, consider using HAL as the Hypermedia implementation.

Examples

Example of Using the Link Header

Link: <http://api.example.com/users/1/friends>; rel="friends"

Example of JSON Representation without HAL

{
  "links": {
    "self": "http://api.example.com/users/1",
    "friends": "http://api.example.com/users/1/friends"
  },
  "name": "John Doe",
  "age": 30
}

References

• Pragmatic-rest-apis-without-hypermedia-and-hateoas
• REST v.s. Hypermedia - hot or not?