Resource Collections

Most Apiture Open Banking APIs divide their resources into collections. The API reference indicates if an object is a collection, for example, see the descriptions of accounts, scheduledTransfers, and transactions.

Collections have fixed URL names, such as:

• /accounts/accounts/
• /transfers/scheduledTransfers
• /transactions/transactions

Collections contain instances, which are identified with a unique resource identifier (resourceId for short). The resourceId is a URL path variable which varies from instance to instance.

Examples:

This URI structure is described in Resources and URI Structure.

The Hypermedia Application Language (HAL) representation of a collection uses HAL’s embedded object as a container of an array of items. Below is a skeletal JSON representation of a collection of items:

{
  "name": "transfers",
  "_embedded": {
    "items": [
      {
        "description" : "transfer 0",
        "_links": {
          "self": {
            "href": "/uri/for/transfer-0"
          }
        }
      },
      {
        "description" : "transfer 1",
        "_links": {
          "self": {
            "href": "/uri/for/transfer-1"
          }
        }
      },

      "..." : " ... more items ... ",

      {
        "description" : "transfer n",
        "_links": {
          "self": {
            "href": "/uri/for/transfer-n"
          }
        }
      }
    ]
  }
}

Each of the items in a collection is a concise summary representation of the complete resource. The summary representation includes:

• An item’s key properties
• A link with the link relation self. Use this link to get all of the properties and relevant links for the item.

The API reference shows that collections have an _embedded.items array containing a summary representation of that collection. See the embedded.items array in:

• accounts containing summaryAccount items
• scheduledTransfers containing summaryScheduledTransfer items
• transactions containing summary transaction items

In addition to the items array, every collection extends the base collection schema and includes these properties:

• The name of the collection items
• The pagination start and limit. See paginating through larger collections.
• An optional count of items in the collection (if the service can compute the count efficiently). Note: If a filter has been applied to the collection, the count reflects the number of items that satisfy the filter. In most cases, when filtering is applied, the count is not efficiently computable, so it is omitted instead.

Working with Collections

Most collection resources in Apiture Open Banking APIs support:

• Paginating through larger collections
• Applying a filter
• Searching for text strings
• Sorting based on one or more keys