Links

In Apiture APIs, request and response bodies use HAL HYPERMEDIA format which can contain links to related resource and operations. A HAL response may contains an object named _links which contains a mapping of link relation names to link objects.

  • A link relation name is a mnemonic string which describes the meaning of the link.
  • The value is a link object which contains an href (a URL) of the target resource or operation and other optional link properties based on the Atom link specification. The IANA standards body maintains a registry of link relation names and their meanings.

These links can refer to other resources that are related to the resource, or they can refer to operations that are available for a resource. For example, in the Transfers API, a scheduled transfer will have a link to the source account and another link to the target account. The scheduled transfer may also have links to operations which suspend or cancel the scheduled transfer.

Each link object contains a required href field and additional optional fields defined by HAL link objects:

  • href (required)
  • templated
  • type
  • deprecation
  • name
  • profile
  • title
  • hreflang

While Apiture APIs use href in all links, the other link properties are much rarer.

Apiture APIs return links to operations only if that operation is available to the authenticated caller. For example, if a scheduled transfer is active, there will be a link to suspend it, but not a link to resume the transfer. Once the transfer has been suspended there will be a link to resume it, but not a link to suspend the transfer.

If a link in an Apiture API can be identified with a standard IANA link relation, that name is used. Examples are prev and next for collection pagination, or the link self which is a link to the current resource. For other link relations that are not in the IANA list, Apiture APIs use an apiture: prefix. Examples of the prefix include apiture:source and apiture:target for a transfer of funds between a source account and a target account, or apiture:close and apiture:freeze for links to close or freeze an account.