Links

In Apiture Open Banking APIs, request and response bodies use Hypermedia Application Language (HAL) format. A HAL payload may include an object named _links. This object contains links to the resource itself, other resources related to it, or to operations available to the resource. For example, in the Transfers API, a scheduled transfer can 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.

Example

  "_links": {
    "self": {
      "href": "/transfers/scheduledTransfer/0399abed-fd3d-4830-a88b-30f38b8a365c"
    },
    "apiture:source": {
      "href": "/accounts/accounts/1dcddbf8-ef88-4e4e-b2f1-4bc54d66595e"
    },
    "apiture:target": {
      "href": "/accounts/externalAccounts/7ffe0043-37a8-4aac-9ef3-43b586fa00fe"
    },
    "apiture:cancel": {
      "href": "/transfers/canceledScheduledTransfers?transfer=0399abed-fd3d-4830-a88b-30f38b8a365c"
    }
  }

Essentially, the _links object 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 IANA standards body maintains a registry of link relation names and their meanings.
• 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.

Each link object contains a required href property and additional optional properties defined by HAL link objects:

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

Apiture Open Banking APIs use href in all links. The other link properties are much rarer.

Apiture Open Banking 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 Open Banking API can be identified with a standard IANA link relation, Apiture Open Banking APIs use that link relation. 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 Open Banking APIs use an apiture: prefix. Examples of link relations with the prefix include apiture:source and apiture:target for links to transfer funds between a source account and a target account, or apiture:close and apiture:freeze for links to close or freeze an account.