patterntypescriptTip

HAL Format: Hypermedia API links for navigable REST APIs

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

halhateoaslinkshypermediarest_linksself

Problem

REST APIs that return only data leave clients hardcoding URL patterns. When URLs change, all clients must be updated. HATEOAS promises navigable APIs but lacks a widely adopted format.

Solution

Use HAL (Hypertext Application Language) to embed _links in responses. Include a self link on every resource and action links for available transitions. HAL is simple, well-supported, and machines can discover API capabilities dynamically.

Why

HAL-enabled clients can follow links rather than constructing URLs, making them more resilient to API evolution. The _embedded convention allows including related resources without a separate spec.

Gotchas

HAL adoption is low among modern API consumers — evaluate whether your consumers will use the links or ignore them.
HAL does not define error formats, filtering, or pagination beyond links — combine with a pagination convention.
The _links and _embedded properties must be reserved — do not use them as data fields.

Code Snippets

HAL resource with links

const userResponse = {
  id: '42',
  name: 'Alice',
  email: 'alice@example.com',
  _links: {
    self: { href: '/users/42' },
    posts: { href: '/users/42/posts' },
    deactivate: { href: '/users/42/deactivate', method: 'POST' }
  },
  _embedded: {
    latestPost: {
      id: '1',
      title: 'Hello World',
      _links: { self: { href: '/posts/1' } }
    }
  }
}

Revisions (0)

No revisions yet.