Resource Collections

Most Apiture APIs divide their resources into collections which contain instances. Collections have fixed URL names, whereas each instance is identified with a unique resource identifier (resourceId for short). The resourceId is a URL path variable which varies from instance to instance.

Some examples:

  • The Accounts API has two collections, /accounts/accounts and /accounts/externalAccounts. An internal account instance has the URI /accounts/accounts/{accountId}; external accounts are at /accounts/externalAccounts/{externalAccountId}.
  • The Transfers API has /transfers/scheduledTransfers and /transfers/pastTransfers collections, and instances /transfers/scheduledTransfers/{scheduledTransferId} and /transfers/pastTransfers/{pastTransferId}.
  • The Transactions API has a /transactions/transactions collection and instances /transactions/transactions/{transactionId}.

Thus URI structure is described in Resources and URI Structure.

The HAL representation of a collection uses HAL’s _embedded object as a container of an array of items. Normally, this is a single page of items from the complete collection. 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"
          }
        }
      }
    ]
  }
}

The items in the collections are normally concise summary representations of the complete resource. This summary representation contains a subset of properties that most clients need; these are the key properties. The summary representation also contains a link with the link relation name self; this link is the URI of the embedded item. Clients can GET the full representation via the self link to get all the properties and relevant links that the service provides for that resource. For example, the summary representation will provide properties that the client can display in a table or list representation.

Each collection is defined by a schema which extends the base collection schema. The base collection schema includes these properties:

  • the name of the collection items
  • the pagination start and limit (described below)
  • an optional count of items in the collection (if the service can compute the count efficiently). If a filter has been applied to the collection, the count reflects the number of items that satisfy the filter, but in most cases, when filtering is applied, the count is not efficiently computable, so it is omitted instead.

Specific collection schemas (such as accounts in the Accounts API, or scheduledTransfers in the Transfers API) also define _embedded.items to be an array containing a page of items from that collection. Thus, accounts contains a _embedded.items array of account objects, using the summaryAccount schema.

Most collections resources in Apiture APIs support paginating through larger collections, filtering the collection to a subset by applying a filter or my searching for text strings, and sorting based on one or more sorting keys.