API Migration Guide - StatusCake Knowledge Base

Later this year we’ll be sunsetting the current unversioned API. When this happens any requests made to https://app.statuscake.com/API/* will be rejected. However until this time, and moving forward, we’re introducing a new set of API endpoints that we are versioning under the v1 namespace. These API endpoints will be hosted at https://api.statuscake.com/v1. The full documentation can be found here. The rest of this document describes some of the less obvious details when migrating from the old API to the new.

Authentication

Authentication is handled using HTTP request headers and the Authorization field. Any request authenticating using form parameters or query strings will no longer be accepted.

Additionally only the API key is necessary when making authenticated requests. Previously an authenticated request would need to include the username of the account associated with the API key. However, this is now redundant.

An authenticated HTTP request must take the form (some fields omitted):

GET /v1/uptime-locations HTTP/2
Host: api.statuscake.com
Authorization: Bearer abc123

A failed authentication request will return the following HTTP response

HTTP/2 403
x-ext-authz: denied

Ratelimiting

Ratelimits are imposed such that any account without a package (free account) will be subject to a maximum of 60 requests per minute. Paid accounts are only subject to a limit of 5 requests per second.

Ratelimits are imposed per account as opposed to per API key. That is, an account with multiple API keys will share a ratelimit between all API keys associated with that account.

When the ratelimit is exceeded the API will respond with a HTTP 429 status code.

Errors

HTTP response codes are returned consistently and in keeping with HTTP semantics. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted or malformed). Codes in the 5xx range indicate an error with StatusCake servers.

Request Content Types

The only supported request content type is application/x-www-form-urlencoded. This is the same as the previous API. In future, this may be extended to include JSON.

Response Content Types

Responses for all endpoints support only the JSON format. Endpoints for monitoring locations in the previous API allowed for plain text (newline delimited) and XML response types. This is no longer supported and API consumers will need to implement JSON parsing to continue to use these endpoints.

All API endpoints return a JSON object at the root of the response. On a successful response, the JSON object will contain a data attribute containing the relevant resource data. Depending on the request this will either be an array or an object.

{
  "data": {
    "id": "1111",
    "paused": false,
    "name": "example HTTP test",
    "test_type": "HTTP",
    ...
}

In the case of an error, the JSON object will contain an object listing the issues that must be resolved before the request will succeed. For example:

{
  "message":"The provided parameters are invalid. Check the errors output for detailed information.",
  "errors":{
    "check_rate":["Check Rate is required","Check Rate must be an integer"],
    "name":["Name is required"],
    "test_type":["Test Type is required","Test Type contains invalid value"],
    "website_url":["Website Url is required"]
  }
}

Pagination

For endpoints that support it, pagination data is returned within a metadata an object within the JSON response.

{
  "data": [
    ...
  ],
  "metadata": {
    "page": 1,
    "per_page": 1,
    "page_count": 1,
    "total_count": 1
  }
}

Request Routes

Each HTTP operation now has its own dedicated endpoint. Unlike previously where a single endpoint may have been shared for POST, PUT and sometimes DELETE operations, the API now separates these and allows for conventional HTTP semantics. For example, to create and update an Uptime monitoring test an API consumer would make a request to POST /v1/uptime and PUT /v1/uptime/:id respectively. The API documentation outlines all the endpoints available.

Setting Regions on Uptime Tests

Selecting specific servers that Uptime monitoring tests run is no longer supported. This is to prevent degradation of performance across small numbers of servers taking on most of the work. Instead, API consumers can select the region that their tests run. This is exactly the same process employed by the StatusCake UI. This allows us to better optimise test loads across our fleet of monitoring locations and prevent a poor user experience.

We continue to bind server locations(s) to a test at test creation so that customer firewall listings can be maintained. However, this is subject to change and entire regions may need to be listed in order for tests to be successful.

Consistent Datetime Format

All DateTime values returned from the API are formatted to the RFC3339 standard unless stated otherwise in the documentation. Details of this standard may be found in its specification and will be returned in each API response in the form 2017-11-04T11:58:23+00:00.

No Public Reporting Endpoints

Public Reporting endpoints do not currently feature in the API. This may change in future releases.

New Maintenance Windows Endpoints

The Maintenance Windows endpoints currently featured in the API work exclusively with the most current version of the Maintenance Windows feature. All new accounts since 10 November 2020 will have been automatically enrolled onto the newer version and may therefore make use of these endpoints. Whilst the new version of maintenance windows was released last year, available on the StatusCake UI, with better support for timezones.

If you haven’t transferred your new maintenance windows to the new version you will still (for now) be able to use the deprecated Maintenance Windows API endpoints located here.

Knowledge Base