Resources and URI Structure

Apiture Open Banking APIs center on REST concepts of transferring representations of resources and application state. Resources are the banking business objects, such as users, accounts, transfers, files, transactions, statements, and so on. Resources may either be collections or instances which reside in collections. Each resource, whether it is a collection or an instance, has a unique Uniform Resource Indicator or URI, which serves as the address of that resource. Use the URI to access a resource.

URIs

A URI is the address of a resource. Apiture Open Banking APIs use “clean URIs” which aid in understanding the API resource structure. As addresses of resources, URIs are nouns. The HTTP verbs GET, POST, PUT and DELETE convey the action of the request. Think of GET as an alias for “Read”, POST as an alias for “Create”, and PUT as an alias for “Update”. Translate each operation into an imperative sentence:

  • Read POST /transfers as “Create a new resource within the transfers collection”
  • Read PUT /users/u123 as “Update user u123”

The URIs of Apiture Open Banking APIs do not contain verbs. Verbs in URIs do not allow us to extend the API with PUT, GET, DELETE, or define instances beneath the verb. When URIs are nouns, we can always extend the API. For example, GET /validations returns a collection, and we can extend it to the operation GET /validations/{validationId}.

Resource URI Structure

The URIs of Apiture Open Banking APIs follow a consistent structure that reflects the resources of each API.

Path Description
/<apiName>/ The root of the API, from which the rest of the API may be discovered.
Examples:
/accounts/
/transfers/
/<apiName>/<collectionName> A collection of resources within the API. The response to the GET /apiName/ call contains a link to this collection.
Examples:
/accounts/externalAccounts
/transfers/scheduledTransfers
/<apiName>/<collectionName>/{instanceId} An instance is a resource in the named collection with a unique identifier string, the {instanceId}.
Example:
/accounts/externalAccounts/c276fda5-b631-49f2-8911-13c6ad6264da

In the the third example above, {instanceId} denotes a path variable, a string consisting of ASCII characters, which varies from instance to instance. For example, the path pattern for an external account is /accounts/externalAccounts/{externalAccountId}. Replace the path variable {externalAccountId} with the unique ID of an external account, such as c276fda5-b631-49f2-8911-13c6ad6264da. This gives the URI for the specific external account: /accounts/externalAccounts/c276fda5-b631-49f2-8911-13c6ad6264da. Note: An account ID is not the same as the account number. We do not use account numbers in URIs for security reasons.

API Root

Each Apiture Open Banking API has a top-level root that corresponds to the API name. The root of the Accounts API is /accounts/.

The API root operation, such as, the Accounts API operation GET /accounts, returns a set of links to the top level resources in the API; these are typically collections. For example, GET /accounts/ returns links to the top level collections (/accounts/accounts 1 and /accounts/externalAccounts) as well as links to operations to create new resources in those top level collections.

Links at the top of the API do not include links that apply to instances within collections. You can discover links on an item from the instance resource.

  1. It is common for a top-level collection to have the same name as the API name. The primary collection in the Accounts API is also named accounts, yielding the path /accounts/accounts to the collection of accounts. ↩