HTTP for API Transport
Resources and URI Structure
Hypermedia Application Language (HAL)
Representation Profiles and Schemas
Optimistic Locking and Concurrency
Error Responses and Error Representation
HTTP for API Transport
Apiture 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][resourceSets].
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 observable effect on the resources in the system.
- Apiture 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.
- Responses contain an HTTP response code. Common response codes are:
- 200 - OK
- 201 - Created
- 204 - No Content
- 400 - Bad Request
- 401 - Unauthorized (no authentication was passed)
- 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 - 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
- Response bodies (typically JSON HAL) are representations of the created, modified, or requested resource.
- All resources have URIs.
As part of the uniform interface
constraint of REST APIs, Apiture APIs rely on URI as the address of application resource.
For REST applied over the HTTP transport, the HTTP verbs to indicate the action to perform on those resources.
Thus, the Apiture APIs do not contain verbs in the URI paths.
Actions that are not easily captured with the standard HTTP verbs
POST == create,
GET == read,
PATCH == update,
DELETE == delete)
are modeled through
POST operations and either creating new resource,
or moving resources into resource sets.
For example, to freeze a bank account, one will
POST the account resource URI or resource ID
/accounts/frozenAccounts resource set.