Skip to content

Basic Usage

Base URL

The API is accessible under the following URL:

https://surfmeter-server.<host>/export_api/v1

The hostname depends on your customer name and will be communicated to you.

Authentication

Accessing the API requires a valid API key in order to authenticate against the server. Each request to the API must be passed an API key. The API key(s) will be communicated to you separately. If you haven't been supplied an API key, please contact us.

To avoid having the API key stored in plaintext in your console log (or other query logs), you should send the API key as an HTTP header called X-API-KEY:

curl -H "X-API-KEY: ABCDE" \
    "https://surfmeter-server.<host>/export_api/v1/measurements"

Note

If a 403 error is returned via the API, please verify that the API key has not expired, or that you have not made too many requests. Each customer may have multiple API keys, and API keys may expire. There is a rate-limitation for requests in place to prevent server overload.

Content Type

Each request should be made with the appropriate HTTP accept headers for the response, e.g. for JSON:

curl -H "Accept: application/json" \
    -H "X-API-KEY: ABCDE" \
    "https://surfmeter-server.<host>/export_api/v1/measurements"

Parameters

Any parameters (as defined in the resources) should be passed as query parameters, e.g.:

https://surfmeter-server.<host>/export_api/v1/measurements?start_time=2021-01-01T00:00:00Z&end_time=2021-01-02T00:00:00Z

If an array parameter is to be used, you can either specify the same parameter multiple times, or use a comma-separated list, so these two queries are equivalent:

https://surfmeter-server.<host>/export_api/v1/measurements?tags[]=foo&tags[]=bar
https://surfmeter-server.<host>/export_api/v1/measurements?tags=foo,bar

Pagination

If a resource returns multiple elements, only a limited number of elements can be returned at once. If this is the case, the response will include the following HTTP headers:

  • Per-Page: The number of elements shown per page
  • Total: The number of total elements available
  • Link: A set of links following the RFC 8288 standard, which indicate how to query the other elements.

In order to query the next page of elements, the page parameter has to be added to the subsequent request. For example, to request the second page of resources, query:

https://surfmeter-server.<host>/export_api/v1/measurements?page=2

In order to limit the number of results per page, you can use the per_page parameter:

https://surfmeter-server.<host>/export_api/v1/measurements?page=2&per_page=100

Note that the maximum number of elements returned per page are 1,000.

In the next section you'll see the resources that are available.