Using the Hub API¶
The Hub API is a RESTful interface allowing you to programmatically access the same functions you may also already access using the Hub web interface.
The API has predictable resource-oriented URLs, accepts only JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication and verbs.
Forming URLs¶
Each API command is available at a specific endpoint. To trigger this endpoint you need to construct an appropriate URL. Hub URLs are made up of three parts:
BASE URL + API PATH + ENDPOINT
The base URL for Hub is always https://hub.nuvias-uc.com
.
The API path specifies the major API version you wish to access. Currently only one API path is available: /api/v1
.
The endpoint will depend on which function you wish to call.
For example, the POST /orders
endpoint can be used to create a new order. Its full URL is: https://hub.nuvias-uc.com/api/v1/orders
.
Filtering results¶
Where a list API allows filtering, the rules between different parameters are applied as ANDs, while a parameter with multiple values are applied as ORs.
For example, if a filter query string was organisation=5&organisation=10&type=invoice
this would look for invoices only with an organisation ID of 5 or 6.
Pagination¶
Pagination is achieved with two parameters that are applied consistently across the API.
per_page
determines the number of results desired in a given page.page
starts at 1 and determines the page of results you wish to view
For example, if per_page
is set to 24
and page
is set to 2
you will receive results 25-48.
Results will include the X-Total-Count
and X-Total-Pages
headers to tell you the total number of results, and the total number of pages.
If you don't specify per_page
then a suitable default will be used. This is currently 1000
in most cases, but may vary from one endpoint to another and may be changed without notice. You cannot set per_page
any higher than 1000
.
Sample code¶
A small demonstration of the Hub API is available from https://github.com/nuvias-uc/hub-api-sample-python