Skip to content

badgateway/hal-types

Repository files navigation

Typescript types for HAL documents

This repository exports a set of typescript types for HAL documents.

It exports the following interfaces:

  1. HalLink, representing an individual HAL Link
  2. HalResource, representing a single HAL document, with at least a _links property and optionally _embedded property and _templates properties.
  3. LinkHints, an extension to links, as defined in draft-nottingham-link-hint.
  4. HalFormsTemplate, A HAL Forms template object.
  5. HalFormsProperty A single property from a HAL Form.

Usage

This example shows how to create a TypeScript type for your HAL-based resource, by extending the HALResource type.

import { HalResource, HalLink } from 'hal-types';

export type ExampleResource = HalResource & {
  _links: {
    copyright: HalLink;
    related?: HalLink[];
    "http://example.net/foo": HalLink;
  }
  _embedded: {
    alternate: HalResource;
    collection?: HalResource;
    author: HalResource[];
  }
  title: string;
  pageCount?: number;
  description: {
    summary: string;
    introduction: string;
  };
}

Note that the self link does not need to be included as this is already provided by HalResource.

While this is not readily apparent in this example, the properties within the _links and _embedded objects must be Link Relations (though this is not enforced). This example mostly uses registered Link Relations which you can refer to by name. In many cases, you will need to use custom Link Relations (called extension relation types), which take the form of a URI (e.g. the link http://example.net/foo in this example).