Skip to main content

REST

The API is resource-oriented and stateless. Most resources are either list resources or entity (object) resources, although a few special RPC resources also exist.

List Resources

A list resource responds to the HEAD, GET, POST and OPTIONS HTTP methods.

MethodDescription
OPTIONSReturns metadata about the resource's API; for instance, a list of available HTTP methods are returned in the Allow HTTP header.
GETRetrieves entities and metadata from the list.
HEADHEAD is just like GET, except that it only returns metadata.
POSTCreates and appends a new entity (which should be supplied in the request body) to the list.

GET on a list resource simply returns the first 1000 entities in the order they were created, as a list. The following query parameters can be used to alter the response:

NameMeaningDescription
qQueryUsed to filter what entities to return. See Query language.
sSort OrderName of the field to use as sort key. Nested fields should be separated by a dot (e.g. receipt.id sorts by the receipt ID). May be prepended by a - sign to reverse the sort order.
oOffsetThe starting index in the sorted list to return. Used for pagination and defaults to 0.
cCountThe number of entities to return. Defaults to 1000.
dDeletedSet to t (true) to also return entities that have been deleted. Defaults to f (false).

The ETag HTTP header can—and should—be used together with If-None-Match to avoid sending the response if it's unchanged since the last time the client asked.

Response Codes

The following response codes may be returned when accessing a list resource:

CodeMeaningDescription
200OKRequest succeeded.
201CreatedRequest to create a new entity succeeded.
202AcceptedA special case: A duplicate entry was posted to the journal.
304Not ModifiedA GET request with If-None-Match would have returned a body that the client already has in its cache.
400Bad RequestReturned if the request is somehow malformed, for instance if a required path component is missing or invalid, or if the Authorization header is malformed.
401UnauthorizedUsed to request a valid Hawk Authentication header from the client. See Authentication & Authorization.
402Payment RequiredThis resource is part of an optional feature package, which is not enabled for the current account.
403ForbiddenBased on the authentication supplied, the client does not have permission to perform the current action.
404Not FoundThis resource does not exist.
405Method Not AllowedThe HTTP method used is not supported for this resource. You may use OPTIONS to find out what verbs are supported for a given resource.
406Not AcceptableThe response cannot be encoded according to the Accept or Accept-Charset request headers.
408Request TimeoutThe client did not send the complete request body in time.
409ConflictA POST request was unable to add the entity because of a unique constraint violation. One of the entity's properties conflicted with an existing entity.
411Length RequiredThe Content-Length request header is missing.
413Request Entity Too LargeThe client tried to POST an entity that exceeded the maximum allowed size.
414Request URI Too LongThe request URI (including the query parameters) is too long.
415Unsupported Media TypeThe request's Content-Type is not supported, or the entity body could not be parsed. See Entity Formats for more information regarding supported formats.
422Unprocessable EntityThe request entity could be parsed but did not pass validation. Properties may be missing or have an incorrect format.
500Internal Server ErrorThe request failed because of a server bug or an exceptional condition.
502Bad GatewayThe service is currently not working correctly.
503Service UnavailableThe service is currently not working correctly.
504Gateway TimeoutThe service is currently not working correctly.

Entity Resources

An entity resource responds to the HEAD, GET, PUT, PATCH, DELETE and REPORT HTTP methods and always accesses a single entity/object, identified by its id property. Entities are always accessed by appending the id to the list resource URL (that is, if the product list resource is available as .../products, then product #1 is addressable as .../products/1).

The ETag HTTP header may be used together with If-Match or If-None-Match to make the operations on entity resources conditional and to avoid race conditions when multiple clients operate on the same entity, or just to reduce network traffic for GET requests.

MethodDescription
OPTIONSReturns metadata about the resource's API; for instance, a list of available HTTP methods are returned in the Allow HTTP header.
GETRetrieves the entity. A d (for "deleted") query parameter set to t (true) may be used to retrieve deleted entities.
HEADHEAD is just like GET, except that it only returns metadata.
PATCHModifies an entity by replacing all properties supplied in the request body, leaving any other existing properties unmodified.
PUTCompletely replaces the entity with a new one, supplied as the request body.
DELETEMarks a resource as deleted. (A deleted resource may be undeleted at any time by using PATCH to set its deleted property to null.)
REPORTInspired by WebDav, this method can be used to inspect the entity's revision history.

Note that the POST method is not used on standard entity resources.

Some very old firewalls, proxies or HTTP libraries may not allow request methods such as PATCH, PUT, DELETE or REPORT. In these cases, it's possible to issue a POST request with the request header X-HTTP-Method-Override set to the actual HTTP method.

POST /v1/~realm/products/1 HTTP/1.1
Host: test.onslip360.com
X-HTTP-Method-Override: DELETE

The example above marks product #1 as deleted.

Response Codes

The following response codes may be returned when accessing an entity resource.

CodeMeaningDescription
200OKRequest succeeded.
204No Content †A DELETE request (without the d query parameter set to t) succeeded.
205Reset Content †An individual property was modified by a PUT or DELETE request.
304Not ModifiedA GET request with If-None-Match would have returned a body that the client already has in its cache.
400Bad RequestReturned if the request is somehow malformed, for instance if a required path component is missing or invalid, or if the Authorization header is malformed.
401UnauthorizedUsed to request a valid Hawk Authentication header from the client. See Authentication & Authorization.
402Payment RequiredThis resource is part of an optional feature package, which is not enabled for the current account.
403ForbiddenBased on the authentication supplied, the client does not have permission to perform the current action.
404Not FoundThis resource does not exist.
405Method Not AllowedThe HTTP method used is not supported for this resource. You may use OPTIONS to find out what verbs are supported for a given resource.
406Not AcceptableThe response cannot be encoded according to the Accept or Accept-Charset request headers.
408Request TimeoutThe client did not send the complete request body in time.
409ConflictA PATCH or PUT request was unable to modify the entity because of a unique constraint violation. One of the updated entity's properties conflicted with an existing entity.
410Gone †The resource exists but has been deleted.
411Length RequiredThe Content-Length request header is missing.
412Precondition Failed †Returned if an If-Match or If-None-Match precondition did not succeed.
413Request Entity Too LargeThe client tried to POST an entity that exceeded the maximum allowed size.
414Request URI Too LongThe request URI (including the query parameters) is too long.
415Unsupported Media TypeThe request's Content-Type is not supported, or the entity body could not be parsed. See Entity Formats for more information regarding supported formats.
418I'm a TeapotThe request is not applicable to this type of entity.
422Unprocessable EntityThe request entity could be parsed but did not pass validation. One or more properties are missing or have incorrect format.
500Internal Server ErrorThe request failed because of a server bug or an exceptional condition.
502Bad GatewayThe service is currently not working correctly.
503Service UnavailableThe service is currently not working correctly.
504Gateway TimeoutThe service is currently not working correctly.
† This response code is exclusive to entity resources and does not apply to list resources.