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: POST, PUT, GET, DELETE, 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][resourceSets].
    • 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 observable effect on the resources in the system.
    • Apiture 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
    • 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 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 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, PUT and 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 to the /accounts/frozenAccounts resource set.