HTTP for API Transport

Apiture Digital 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 Digital 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.
• All resources have URIs that are URLs.
• Responses often include standard HTTP 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.
• Responses contain an HTTP response code. Common response codes are:
  • 200 - OK — The operation succeeded.
  • 201 - Created — Created a new resource.
  • 202 - Accepted — The service has accepted the request and continues to process it after returning.
  • 204 - No Content — There is no response body. (Usually the response from DELETE operations.)
  • 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 conflicts with the state of the system or, if completed, would result in a conflict or inconsistency.
  • 412 - Precondition Failed — Concurrent modification detection: The If-Match entity tag does not match the resource (meaning, the resource has been changed elsewhere).
  • 422 - Unprocessable Entity — The request is valid syntactically but the content is not consistent, incomplete, or does not make sense semantically.
  • 409 - Conflict — The request is inconsistent with the state of the resource.
  • 5xx errors indicate that an error has occurred in the service.
  • For 4xx and 5xx errors, the response contains a common error description.

The above list is not comprehensive.

The API definitions list the most common HTTP response codes for each operation, but those lists are not comprehensive.

For example:

• All operations may return a 401 Unauthorized if the API Key is omitted in the request or if the Authorization header is omitted for operations which have a oauth2 security requirement.
• All operations may return a 403 Forbidden.
• All operations which reference resources (normally through path parameters) may return 404 Not Found, 410 Gone, or 403 Forbidden.
• All operations which accept a request body, query parameters, or header parameters my return 400 Bad Request or 422 Unprocessable Entity.
• The API services may return 405 Method Not Allowed, 406 Not Acceptable for incorrect API calls (wrong HTTP method or wrong Accept header, respectively)
• All clients should be prepared for any operation to return 429 Too Many Requests and throttle their call rates accordingly.

Clients should be robust enough to handle any valid HTTP response code, including 3xx response codes, not just those defined in the OpenAPI definitions.

Uniform Interface

As part of the uniform interface constraint of REST APIs, Apiture Digital 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 Digital 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.