This chapter takes a close look at the API. If you’re looking for a brief introduction, check our Quick Start tutorial.
HubRise API is based on a REST protocol, where methods such as POST, GET, PATCH/PUT and DELETE let you create, retrieve, list, update and delete resources. Data is transmitted in the JSON format.
An endpoint is an API operation. It comprises a URL and HTTP method. Endpoints URLs are rooted at https://api.hubrise.com/v1.
Versions are included in the endpoints URLs for compatibility purposes. No breaking change will be made without changing the version, and old versions will be supported for a while.
Every API request must include an access token, which uniquely identifies the connection. The token is passed in the
Access tokens are acquired via OAuth 2.0. See Authentication.
Note: further in this documentation, the root part of the request URLs will be omitted. In the example above, we would simply use: GET /location/orders
Index endpoints (eg
GET /location/orders) paginate the results. A maximum of 100 results are returned.
If the results cannot be returned in a single response, the endpoint returns the first set of results, along with a
X-Cursor-Next response header. To get the next set of results, a new request including the previously returned header must be made. Repeat until no
X-Cursor-Next header is sent back, which indicates that the last set has been returned.
Every index endpoint accepts 2 optional parameters:
count: the maximum number of results to return per request. The default (and maximum) value is 100. Decrease this value if needed.
cursor: the next subset of results to return. Must be set to the value received in the previous
X-Cursor-Nextresponse header to iterate through the results. If this parameter is omitted, the first set of results is returned.
If a connection makes too many requests in a short time window, HubRise will return a
429 (Too Many Requests) HTTP status code.
A connection is limited to 500 requests per 60-second window.
Some HTTP clients can only send GET and POST requests.
To increase accessibility to these limited clients, the HTTP method can be overridden by setting the
X-Http-Method-Override header in a POST request:
This parameter is not accepted in a GET request, since a GET request should not change the state of a resource.
A number with 2 decimal digits, followed by a space and the ISO 4217 currency name. Can be preceded by a
- sign for negative amounts.
Encoded using the ISO 8601 format. A date/time passed to the API is assumed to be in the location’s timezone, unless otherwise specified. The API returns times in the local timezone, with the timezone explicitly specified.
- Explicit timezone:
- Assume location’s timezone:
Can be one of
The API returns appropriate HTTP status codes for every request.
||Not Modified||There was no new data to return|
||Bad Request||The request was invalid or cannot be otherwise served. An accompanying error message will explain further.|
||Unauthorized||Authentication credentials were missing or incorrect.|
||Forbidden||The request is understood, but it has been refused or access is not allowed.|
||Not Found||The URI requested is invalid or the requested resource does not exist.|
||Unsupported Media Type||The provided Content-Type is not supported.|
||Too many requests||You have reached the rate limit for the resource.|
||Internal Error||Something is broken. The HubRise team has been notified and is investigating.|
HubRise returns comprehensive error messages when the request cannot be processed.
An error response looks like this:
The response may also include a field breakdown, like this: