Standards and Conventions
A useful guide to the conventions used within the REST API.
REST Remote Service URL
All the REST remote service resources are accessible through a single URL endpoint:
https://api.opendatadsl.com/api
Security
In order to use the REST API, you need to have a valid ID or ACCESS token and pass that as the Authorization header in the following way:
Authorization: Bearer <IDTOKEN>
Multiple Environments
By default all your requests will be routed to your production environment, but in order to use a different configured user environment, you need to pass an x-odsl-environment header, e.g.
x-odsl-environment: <ENVNAME>
Using GET body for large URLs
For any GET requests to the REST API where the URL is longer than 2048 characters, you can place the query parameters in the BODY of the GET request using the following configuration:
- Set a Content-Type header as
application/x-www-form-urlencoded - In the body, specify the query parameters
The query parameter keys and values are encoded in key-value tuples separated by '&', with a '=' between the key and the value. Non-alphanumeric characters in both keys and values are URL encoded.
Example:
GET https://api.opendatadsl.com/api/object/v1/public
Authorization: Bearer {{token}}
Content-Type: application/x-www-form-urlencoded
_distinct=_type&_filter={_id:/AB/}
Pagination
All the GET methods tagged in the documentation as PAGED break the list of results down into pages which you can control using the following query parameters:
| Parameter | Description | Default |
|---|---|---|
| _limit | The page size | 100 |
| _skip | The number of records to skip | 0 |
As an example:
// Initial request
https://api.opendatadsl.com/api/action/v1/public?_limit=100&_skip=0
// The request to get the next 100 records
https://api.opendatadsl.com/api/action/v1/public?_limit=100&_skip=100
After making the request, you should check the response headers for x-total-count, this tells you the total number of records for the request.
Default page size
If you don't specify a _limit query parameter a default limit of 100 is applied
Unlimited items
You can specify a _limit of -1 for some services and request types to request all items without pagination
All Standard Parameters
The following table is a list of all the standard query parameters and their usage:
| Parameter | Examples | Description |
|---|---|---|
| _sort | _sort={“name”:1, “timestamp”:-1} | Sorts the results of a query according to the field or fields passed in. The value must be 1 for sort ascending or -1 for sort descending |
| _limit | _limit=100 | Limits the number of returned items |
| _skip | _skip=100 | Skips the number of items specified |
| _search | _search=london | Searches the data using the passed in search expression |
| _searchinfo | _searchinfo=lon | Returns a list of ‘auto-complete’ items starting with the expression passed in |
| _distinct | _distinct=location | Returns an array of strings representing a distinct list of values from the named field |
| _reason | _reason=New Data | When added to POST or DELETE calls, sets the reason field in the audit trail |
| _profile | _profile=SPOT | Used in a OBJECT service query to return DATA related to the object |
| _project | _project=name, description | Defines a specific list of fields that you want returned from the service |
| _delay | _delay=60000 | Defines the amount of milliseconds to delay running a manually triggered process |
| _range | _range=last(10) | Defines the date range that you want to return data from a TimeSeries |
| _replace | _replace=true | If set to true with an OBJECT POST query, it will replace the stored object with the provided object instead of merging the data into it |
Ranges
Time-series ranges can be one of:
- last(n) - return the last n values
- from(date) - return all data since date
- between(date, date) - return all data between the 2 dates