Resources and URI Structure

Apiture APIs center on REST concepts of transferring representions 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. The resource’s URI can be passed between APIs when there is a need to reference a resource uniquely.

URIs

A URI is the address of a resource. In pure REST, URIs can be meaningless and opaque. In practice, however, Apiture APIs use “clean URIs” which aid in understanding the API by revealing resource structure of containment (see below.) Clean URIs also aid in development and debugging of APIs and in implementation.

As addresses of resources, URIs are nouns. A URI should not contain verbs – the HTTP verbs convey the action of the request. This is essential to Fielding’s uniform interface constraint of REST. Think of GET as an alias for “Read”, POST as an alias for “Create” and PUT as an alias for “Update”. Each operation should read as an imperative sentence: “POST /transfers” is read as “Create a new resource within the transfers collection”, “PUT /users/u123” is read as “Update user u1234”. If a URI contains a verb, such sentences do not work: the API does not follow the uniform interface constraint. For example, “POST /validate” reads as “Create a validate”. Verbs in URIs also do not allow extending the API by applying PUT, GET, and DELETE, or by defining instances beneath them: DELETE /validate/{validateId} does not work.

Resource URI Structure

Apiture APIs follow a consistent structure which reflects the resources which that API manages.

Each API has a top-level root response which allows discovery of the resources and collections in the API, then one or more resource collections, and then individual resources within those collections.

Path Description
/someApi The root of the API, from which the rest of the API may be discovered
Example:
/accounts/
/someApi/things A collection of “things” within the API. The response to the GET /someApi/ call will contain a link to this collection
Example:
/accounts/externalAccounts
/someApi/things/{thingId} A thing is an item in the collection of things, with a unique identifier string, {thingId}
Example:
/accounts/externalAccounts/c276fda5-b631-49f2-8911-13c6ad6264da

The notation {thingId} denotes a path variable - a string value, consisting of ASCII characters, which varies from resource to resource. The braces {} are not part of the ID. Each resource has a unique identifier in its URI: every thing has a unique {thingId}. For example, the path /accounts/externalAccounts/c276fda5-b631-49f2-8911-13c6ad6264da is the URI for a specific external account; this matches the path pattern /accounts/externalAccounts/{externalAccountId} by replacing the path variable {externalAccountId} with the unique ID of that external account instance, c276fda5-b631-49f2-8911-13c6ad6264da. Note: Account IDs are not related to the account number, which is not part of the account URI for security reasons.

API Root

Each Apiture API provides a self-descriptive resource at the root of the API. This operation returns a set of links to the top level resources in the API; these are typically collections.

For example, for the Accounts API, GET /accounts/ will return links to the top level collections (/accounts/accounts 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 the collection, such as GET or PUT or PATCH /accounts/externalAccounts/{externalAccountId}, as such links on an item are discoverable from those item resources.

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