HTTP for API Transport

Apiture Open Banking APIs are REST APIs built on top of the HTTP protocol¹. A general understanding of HTTP is sufficient to understand how the APIs use HTTP:

• All requests use an HTTP verb: POST, PUT, GET, DELETE, or PATCH.
  • GET is used to read resources, returning (JSON) representations of the requested resource.
  • POST is used most often to create new resources. POST may also be used to perform actions, such as assigning resources to resource sets.
  • PUT is used to update resources. This is a complete replacement of the resource according to the request body profile. Note: Properties which are omitted from the PUT request body are removed or reset to default values.
  • PATCH is used to update resources using a partial representation; only the properties in the request body (or other properties that are derived from them) are changed.
  • DELETE is used to delete resources, if the API allows deletion. Note: Not all resources are deletable. For example, accounts may not be deleted (they may be closed only) after they have been activated.
  • PUT, GET and DELETE are idempotent and safe operations. An idempotent operation is one which has no observable side effects. It may be repeated multiple times without an observable effect on the resources in the system.
  • Apiture Open Banking APIs do not use OPTIONS.
• Requests use HTTP request headers to provide optional metadata about the request, such as Content-Type to provide the media type of the request body, Authorization to provide authorization information, or Accept and Accept-Language to specify the desired representation and language of the response.
• Responses contain an HTTP response code. Common response codes are:
  • 200 - OK — The operation succeeded.
  • 201 - Created — Created a new resource.
  • 204 - No Content — There is no response body.
  • 400 - Bad Request — The request was not well formed or had other errors.
  • 401 - Unauthorized — No authentication information included.
  • 403 - Forbidden — The caller is not authorized to access the resource or perform the requested action.
  • 404 - Not Found — The target resource does not exist.
  • 409 - Conflict — The request is inconsistent with the state of the resource.
  • 500-level — 5xx errors indicate that an error has occurred in the service.
  • For 4xx and 5xx errors, the response contains a common error description.
• Responses include response headers which describe the response, such as Content-Type, Location, ETag.
• Response bodies (typically JSON HAL) are representations of the created, modified, or requested resource.
• All resources have URIs.

Uniform Interface

As part of the uniform interface constraint of REST APIs, Apiture Open Banking APIs rely on the use of URIs as the address of application resources. For REST applied over the HTTP transport, the HTTP verbs indicate the action to perform on those resources.

• POST == create
• GET == read
• PUT and PATCH == update
• DELETE == delete

Thus, the Apiture Open Banking APIs do not contain verbs in URI paths. Actions that are not easily captured with the standard HTTP verbs are modeled through POST operations and either create a new resource, or place resources into resource sets. For example, to freeze a bank account, POST the account resource ID to the /accounts/frozenAccounts resource set.