How to use the API

The article provides information on how to use the V2 API. Basically there are always 2 steps involved:

  • make a request to logging in

  • make subsequent requests using the token returned by the log in request

For more info about how to use filters and so on, refer to the API documentation for details.

API Documentation

Note: SwaggerHub may have small problems, so if the page doesn’t display AFTER redirecting, just do an F5 refresh (sometimes you need to refresh a few times)


The system has 2 types of authentications, but there is only one approach to use the API with the 2 steps below:

  • Step 1: Logging in: (only supports basic authentication) - This is to supply the username and the password to log in and get a token

  • Step 2: Using the api: (only supports bearer authentication) - This is to use a token when making any other requests, so that the system knows who is making the request

Step 1: Logging in:

You can use swagger hub to create an example to show how to log in

  • go to the /token POST endpoint

  • click the lock on the side to open a log in panel

  • enter username and password, hit the authorize button (you don’t have to use your real password here)

  • then expand the endpoint

  • hit Try it out, and execute

  • you get an example to show how to use this API endpoint,

    • including: e.g. 1) the POST method, 2) the URL to use, 3) headers and the most important one is the Authorisation header, with the keyword “Basic” and the base64 encoded username password pair

    • format before encoding: the format before encoding is the username and the password joined by a single colon, which is username:password

    • we support both encoded or clear text here, so both “Basic encoded_pair“ and “Basic username:password“ work

    • here is an example to show additional data you can supply for this request

Refer to the schema section for mandatory or optional data to supply in the request body, these are all optional for authentication.

Step 2: Using the API

You need to supply the token returned by the authentication in order to use the API for e.g. get a category.

To log in:

  • go to e.g. the category endpoint

  • click the lock on the side

  • fill in the token, and this time it’s the token returned by the /token request, not the base64 encoded username password pair

  • again, expand the drop down, click ‘Try it out’ and then ‘Execute’

  • you get an example of how to make such a request

  • in my case, I entered “hello” as the authentication token, just to show how the token is present on the header, in a valid case, the word “hello“ would be a long encoded text