API technical documentation

This page goes into the technical documentation of our API.

The Lizard REST API is used to interact with Lizard data and objects. The API enables to collect, export and manage data. With the API, objects and data can be listed, created, (partially) updated and retrieved. Objects and data have different endpoints, to allow specific interactions.

The endpoints are browseable through the API root view:

Resources are addressable via an URL and can be interacted with via HTTP verbs. The most commonly used and supported verbs are:

  • GET : retrieve data

  • PUT : change data

  • DELETE : delete data

  • POST : add data

We also have HEAD and OPTIONS.

Authentication

When you login via your browser, you get a session-based authentication token that is valid for 24 hours. All subsequent requests to the API are authenticated with that token.

Authenticating to the REST API outside of a browser is done by sending username and password HTTP header fields with every request.

Example request:

GET https://demo.lizard.net/api/v3/locations HTTP/1.1
Host: demo.lizard.net
username: janedoe
password: janespw

For all endpoints, users have to be admin in the organisation that owns the data to create or update resources. See User management for more information about roles and permissions.

Supported data formats

The data formats supported depend on the endpoint, although JSON is generally available. See documentation on the individual endpoints for specifics.

The format of responses can be controlled by specifying an Accept header in requests, e.g. Accept: application/json. When posting data, the format of the payload must be specified via a Content-Type header, e.g. Content-Type: text/csv.

When interacting with the API via a browser, the format query parameter may also be used for controlling the format of the response, for example:

www.demo.lizard.net/api/v3/timeseries/?format=json

Common variables

In this section, query parameters and response fields applicable to all endpoints are described.

Query parameters

The API supports the following common query parameters on GET list requests:

GET /<endpoint>/?page=(int: offset)&page_size=(int: size)
Query Parameters
  • page – offset number; default is 0.

  • page_size – limit number of entries returned; default is 10.

Response fields

All list responses share the following fields.

  • count: number of results for this page

  • next: url to next page, null if last page

  • previous: url previous page, null if first page

  • results: array with actual results

These fields are not specifically mentioned in the response description of each endpoint.

Timeseries

This section describes timeseries-related endpoints.

Locations

This section describes location-related endpoints.