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
In Apiture APIs, request and response bodies use HAL HYPERMEDIA format
which can contain links to related resource and operations.
A HAL response may contains an object named
_links which contains a mapping of
link relation names to link objects.
- A link relation name is a mnemonic string which describes the meaning of the link.
- The value is a link object which contains an
href(a URL) of the target resource or operation and other optional link properties based on the Atom link specification. The IANA standards body maintains a registry of link relation names and their meanings.
These links can refer to other resources that are related to the resource, or they can refer to operations that are available for a resource. For example, in the Transfers API, a scheduled transfer will have a link to the source account and another link to the target account. The scheduled transfer may also have links to operations which suspend or cancel the scheduled transfer.
Each link object contains a required
href field and additional optional fields defined by HAL link objects:
While Apiture APIs use
href in all links, the other link properties are much rarer.
Apiture APIs return links to operations only if that operation is available to the authenticated caller. For example, if a scheduled transfer is active, there will be a link to suspend it, but not a link to resume the transfer. Once the transfer has been suspended there will be a link to resume it, but not a link to suspend the transfer.
If a link in an Apiture API can be identified with a standard IANA link relation, that name
is used. Examples are
next for collection pagination, or the link
is a link to the current resource.
For other link relations that are not in the IANA list, Apiture APIs use an
Examples of the prefix include
for a transfer of funds between a source account and a target account,
apiture:freeze for links to close or freeze an account.