Hypermedia Application Language (HAL)

Apiture Open Banking APIs use the Hypermedia Application Language (HAL) format. HAL is an IETF standard representation for hypermedia APIs, defined by Mike Kelley; JSON HAL defines a JSON representation. The media type application/hal+json identifies a HAL representation content type. It is used in Apiture Open Banking APIs for the produces (response bodies) and consumes (request bodies) types in the OpenAPI documents.

For convenience, the media type application/json may also be used to refer to JSON HAL representation for request and response bodies.

Since JSON HAL describes resource representations with JSON objects, a degenerate HAL object is simply an empty JSON object:

{
}

JSON HAL also defines two optional top-level objects, _links and _embedded, described below. Thus a skeleton of a HAL representation looks like:

{
  "_links" : { },
  "_embedded" : { }
}

However, most JSON representations in Apiture Open Banking APIs contain properties; these appear as top level named values in the JSON object:

{
  "_id" : "46420f2d-1d6c-4802-bb80-51775cc7fda4",
  "_profile" : "http://api.apiture.com/schemas/transfers/scheduledTransfer/v1.0.0/profile.json",
  "amount": {
    "value": "345.50",
    "currency": "USD"
  },
  "description": "Car payment",
  "schedule": {
    "start": "2018-02-05"
  }
}

Thus, almost all Apiture Open Banking API operations return JSON objects. They do not return JSON arrays or JSON primitives, such as, numbers, strings, or booleans. By encoding responses as objects, these responses can be extended in the future by adding new properties.

HAL representations may also contain hypermedia controls; this is an essential component of REST APIs and are used extensively in Apiture Open Banking APIs. JSON HAL defines a _links object which is a JSON object (map) of names/values. Each name is the link relation name. It identifies the _meaning of the link (see the IANA registry which lists several standard link relation names; Apiture Open Banking APIs use the standard IANA link relations where applicable.) The value is a link object with at least the href (URL) of the target resource.

For example, a transfer resource (to transfer funds from one account to another) contains _links to the source and target account resources, as well as top-level properties of the transfer.

{
  "_id" : "46420f2d-1d6c-4802-bb80-51775cc7fda4",
  "_profile" : "http://api.apiture.com/schemas/transfers/scheduledTransfer/v1.0.0/profile.json"
  "_links": {
    "apiture:source": {
      "href": "https://api.thirdpartybank.com/accounts/accounts/46a31698-7398-4538-a9c9-9496010da2c2"
    },
    "apiture:target": {
      "href": "https://api.thirdpartybank.com/accounts/externalAccounts/599b8ab5-6925-4f58-90c5-f6aa5b05f9d9"
    },
    "self" : {
      "href" : "https://api.thirdpartybank.com/transfers/scheduledTransfer/46420f2d-1d6c-4802-bb80-51775cc7fda4"
      }
  },
  "amount": {
    "value": "345.50",
    "currency": "USD"
  },
  "description": "Car payment",
  "schedule": {
    "start": "2018-02-05"
  }
}

HAL is primarily defined for API responses, but Apiture Open Banking APIs also use HAL for request bodies as well. This yields more consistent and uniform APIs: the same format and representation is used when creating resources as is used when fetching resources. For example, when scheduling a transfer, in POST /transfers/scheduledTransfer, the caller passes links to the source and target accounts in the request body:

{
  "_links": {
    "apiture:source": {
      "href": "https://api.thirdpartybank.com/accounts/accounts/46a31698-7398-4538-a9c9-9496010da2c2"
    },
    "apiture:target": {
      "href": "https://api.thirdpartybank.com/accounts/externalAccounts/599b8ab5-6925-4f58-90c5-f6aa5b05f9d9"
    }
  },
  "amount": {
    "value": "345.50",
    "currency": "USD"
  },
  "description": "Car payment",
  "schedule": {
    "start": "2018-02-05"
  }
}

When the client fetches the scheduled transfer, the relationships to the source and target accounts are also represented using links in the response body, in the same format as in the request body, and with the same link relation names. The response may contain additional derived information, such as the current transfer resource’s unique ID and its state:

{
  "_id" : "06372643-b33a-4a1f-98bf-68b23ed0658c",
  "_links": {
    "apiture:source": {
      "href": "https://api.thirdpartybank.com/accounts/accounts/46a31698-7398-4538-a9c9-9496010da2c2"
    },
    "apiture:target": {
      "href": "https://api.thirdpartybank.com/accounts/externalAccounts/599b8ab5-6925-4f58-90c5-f6aa5b05f9d9"
    },
    "self" : {
      "href": "https://api.thirdpartybank.com/transfers/scheduledTransfers/06372643-b33a-4a1f-98bf-68b23ed0658c"
  },
  "state" : "scheduled",
  "visibility" : "visible",
  "amount": {
    "value": "345.50",
    "currency": "USD"
  },
  "description": "Car payment",
  "schedule": {
    "start": "2018-02-05"
  },
  "createdBy": "lucille-4700",
  "createdAt": "2018-05-08T13:37:57.375Z",
  "modifiedBy": "lucille-4700",
  "modifiedAt": "2018-05-18T16:42:57.000Z"
}

Embedded resources

In addition to _links, HAL also reserves the property _embedded as a top-level JSON object. This is used to include optional representations of additional related resources.

An example of embedded resources is in Apiture Open Banking APIs collections. Each collection contains an _embedded object. That object contains several properties which describe the collection, such as name, start, limit, and items (an array of the items in the collection).

Many other representations can include embedded resources. This allows the client API to obtain complete information about a resource without having to make additional GET calls on other resources. For example, an Association resource will include in _embedded, the representations of the source, role, and and target of the association.

Errors

Apiture Open Banking APIs use an _errors object in the top level HAL response if the request has an error (either an error in the user content sent to the API, or a service error in the back end). The _error object in the response contains details about the error. See Error Responses and Error Representation for more information.