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. 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. |
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.
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.
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. |