HTTP for API Transport
Apiture Digital Banking APIs are REST APIs built on top of the HTTP protocol1. A general understanding of HTTP is sufficient to understand how the APIs use HTTP:
- All requests use an HTTP verb:
GETis used to read resources, returning (JSON) representations of the requested resource.
POSTis used most often to create new resources.
POSTmay also be used to perform actions, such as assigning resources to resource sets.
PUTis 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
PUTrequest body are removed or reset to default values.
PATCHis 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.
DELETEis 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.
DELETEare 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
- Requests use HTTP request headers to provide optional metadata about the request, such as
Content-Typeto provide the media type of the request body,
Authorizationto provide authorization information, or
Accept-Languageto 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
- 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
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-Matchentity 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.
- All operations may return a 401 Unauthorized if the API Key is
omitted in the request or if the
Authorizationheader is omitted for operations which have a
- 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
- 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.
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.
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
/accounts/frozenAccounts resource set.