Skip to content

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