Resource Collections

Warning The Apiture Open product line will reach end of life December, 2023. Consumers of the Apiture Open APIs should migrate to the Apiture Digital Banking APIs before that time.


Most Apiture Digital 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:

API Collections URI Instance URI
Accounts API /accounts/accounts
/accounts/externalAccounts		 /accounts/accounts/{accountId}
/accounts/externalAccounts/{externalAccountId}
Transfers API /transfers/scheduledTransfers
/transfers/pastTransfers		 /transfers/scheduledTransfers/{scheduledTransferId}
/transfers/pastTransfers/{pastTransferId}
Transactions API /transactions/transactions /transactions/transactions/{transactionId}

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:

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 Digital Banking APIs support: