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.

Method	Description
OPTIONS	Returns metadata about the resource's API; for instance, a list of available HTTP methods are returned in the Allow HTTP header.
GET	Retrieves entities and metadata from the list.
HEAD	HEAD is just like GET, except that it only returns metadata.
POST	Creates 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. Note that the server will never return more than 1000 entities in a single response. To retrieve more entities, use the o (for offset) query parameter.

The following query parameters can be used to alter the response:

Name	Meaning	Description
q	Query	Used to filter what entities to return. See Query language.
s	Sort Order	Name 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.
o	Offset	The starting index in the sorted list to return. Used for pagination and defaults to 0.
c	Count	The number of entities to return. Defaults to 1000, which is also the maximum allowed value.
d	Deleted	Set 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.

Notable Headers

Type	Name	Description
Request	Accept	Specifies the desired response format. See Entity Formats for more information regarding supported formats.
Request	Accept-Charset	Specifies the desired character encoding of text responses. Default is UTF-8.
Request	Accept-Encoding	Specifies the desired content encoding. Only gzip is supported.
Request	Accept-Language	A few endpoints support this header to specify the desired language of the response. Default is en (English).
Request	Authorization	Used to authenticate the client. See Authentication & Authorization.
Request	If-Match †	Used to make a GET or HEAD request conditional.
Request	If-None-Match †	Used to make a GET or HEAD request conditional.
Response	ETag	A unique identifier for the current revision of the list. Used in conjunction with If-Match and If-None-Match.
Response	Link	Used for pagination. Supported link relations are first, prev, next and last.
Response	X-Total-Count	Used for pagination. The total number of entities in the list that match the query (including deleted entities if d=t is used).

† Note that conditional requests are not supported when creating new entities (i.e. list resource POST requests).

Response Codes

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

Code	Meaning	Description
200	OK	Request succeeded.
201	Created	Request to create a new entity succeeded.
202	Accepted	A special case: A duplicate entry was posted to the journal.
304	Not Modified	A GET request with If-None-Match would have returned a body that the client already has in its cache.
400	Bad Request	Returned if the request is somehow malformed, for instance if a required path component is missing or invalid, or if the Authorization header is malformed.
401	Unauthorized	Used to request a valid Hawk Authentication header from the client. See Authentication & Authorization.
402	Payment Required	This resource is part of an optional feature package, which is not enabled for the current account.
403	Forbidden	Based on the authentication supplied, the client does not have permission to perform the current action.
404	Not Found	This resource does not exist.
405	Method Not Allowed	The HTTP method used is not supported for this resource. You may use OPTIONS to find out what verbs are supported for a given resource.
406	Not Acceptable	The response cannot be encoded according to the Accept or Accept-Charset request headers.
408	Request Timeout	The client did not send the complete request body in time.
409	Conflict	A 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.
411	Length Required	The Content-Length request header is missing.
413	Request Entity Too Large	The client tried to POST an entity that exceeded the maximum allowed size.
414	Request URI Too Long	The request URI (including the query parameters) is too long.
415	Unsupported Media Type	The request's Content-Type is not supported, or the entity body could not be parsed. See Entity Formats for more information regarding supported formats.
422	Unprocessable Entity	The request entity could be parsed but did not pass validation. Properties may be missing or have an incorrect format.
500	Internal Server Error	The request failed because of a server bug or an exceptional condition.
502	Bad Gateway	The service is currently not working correctly.
503	Service Unavailable	The service is currently not working correctly.
504	Gateway Timeout	The 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.

Method	Description
OPTIONS	Returns metadata about the resource's API; for instance, a list of available HTTP methods are returned in the Allow HTTP header.
GET	Retrieves the entity. A d (for "deleted") query parameter set to t (true) may be used to retrieve deleted entities.
HEAD	HEAD is just like GET, except that it only returns metadata.
PATCH	Modifies an entity by replacing all properties supplied in the request body, leaving any other existing properties unmodified.
PUT	Completely replaces the entity with a new one, supplied as the request body.
DELETE	Marks a resource as deleted. (A deleted resource may be undeleted at any time by using PATCH to set its deleted property to null.)
REPORT	Inspired 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.

Notable Headers

Type	Name	Description
Request	Accept	Specifies the desired response format. See Entity Formats for more information regarding supported formats.
Request	Accept-Charset	Specifies the desired character encoding of text responses. Default is UTF-8.
Request	Accept-Encoding	Specifies the desired content encoding. Only gzip is supported.
Request	Accept-Language	A few endpoints support this header to specify the desired language of the response. Default is en (English).
Request	Authorization	Used to authenticate the client. See Authentication & Authorization.
Request	Content-Disposition	When uploading files using Direct Property Access, this header specifies the filename of the uploaded file.
Request	If-Match	Used to make a request conditional.
Request	If-None-Match	Used to make a request conditional.
Request	X-HTTP-Method-Override	Allows the client to override the HTTP method. Useful for clients that do not support certain HTTP methods.
Response	Content-Disposition	Indicates that the response should not be parsed but downloaded as-is. See Direct Property Access.
Response	ETag	A unique identifier for the current revision of the entity. Used in conjunction with If-Match and If-None-Match.

Response Codes

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

Code	Meaning	Description
200	OK	Request succeeded.
204	No Content †	A DELETE request (without the d query parameter set to t) succeeded.
205	Reset Content †	An individual property was modified by a PUT or DELETE request.
304	Not Modified	A GET request with If-None-Match would have returned a body that the client already has in its cache.
400	Bad Request	Returned if the request is somehow malformed, for instance if a required path component is missing or invalid, or if the Authorization header is malformed.
401	Unauthorized	Used to request a valid Hawk Authentication header from the client. See Authentication & Authorization.
402	Payment Required	This resource is part of an optional feature package, which is not enabled for the current account.
403	Forbidden	Based on the authentication supplied, the client does not have permission to perform the current action.
404	Not Found	This resource does not exist.
405	Method Not Allowed	The HTTP method used is not supported for this resource. You may use OPTIONS to find out what verbs are supported for a given resource.
406	Not Acceptable	The response cannot be encoded according to the Accept or Accept-Charset request headers.
408	Request Timeout	The client did not send the complete request body in time.
409	Conflict	A 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.
410	Gone †	The resource exists but has been deleted.
411	Length Required	The Content-Length request header is missing.
412	Precondition Failed †	Returned if an If-Match or If-None-Match precondition did not succeed.
413	Request Entity Too Large	The client tried to POST an entity that exceeded the maximum allowed size.
414	Request URI Too Long	The request URI (including the query parameters) is too long.
415	Unsupported Media Type	The request's Content-Type is not supported, or the entity body could not be parsed. See Entity Formats for more information regarding supported formats.
418	I'm a Teapot	The request is not applicable to this type of entity.
422	Unprocessable Entity	The request entity could be parsed but did not pass validation. One or more properties are missing or have incorrect format.
500	Internal Server Error	The request failed because of a server bug or an exceptional condition.
502	Bad Gateway	The service is currently not working correctly.
503	Service Unavailable	The service is currently not working correctly.
504	Gateway Timeout	The service is currently not working correctly.

† This response code is exclusive to entity resources and does not apply to list resources.