API usage guidelines

The Siteimprove API allows you to access all of your site data through a REST API. The API assumes familiarity with the Siteimprove tools and services.

 

Access and security

The Siteimprove REST API is served over HTTPS only, to support data privacy. Access to the API requires basic access authentication with a Siteimprove user and your API-key as password. See get access on how to obtain access.

 

Accept header

The API serves application/json and text/html content types and will default to text/html. If you specify other media types in the accept: header, the API will respond with a http 406 error. The text/html will allow you to browse the GET requests of the API in a standard browser. To access the entire API from a browser we suggest the use of a REST plugin like Postman.

 

Rate limiting

Usage of the api is limited to 5 request per second per API-key on average with an allowable burst of up to 50 requests. The rate limitation is implemented as a counter with an maximum limit of 50. Each request decrements the counter by 1 until you reach zero. As long as the counter is zero the api returns error code 429. Each second the counter is incremented by 5 until the maximum limit is reached.

You can see the rate limit counter in the response headers named X-Rate-Limit, X-Rate-Remaining and X-Rate-Reset. They show the current maximum limit, the current counter value and the amount of seconds you should wait before the counter is back to the maximum limit.

Example headers in a API response:

This says your maximum limit is 50 requests, of which you have 25 left and in 5 seconds you will be back to maximum if you don’t send any requests in the mean time.

 

Paging

Resources in the API that are paged due to potential large payloads have the general form:

Where items is a slice of items from the total result set. total_items is the total number of elements in the result set. total_pages is the total number of pages for the result set. next takes you to the next page in the result set. Not present on the last page of a result and vice versa for prev.

The default page size is 10 items per page. You can change this to an arbitrary value between 1 and 1000 by setting the page_size url query string parameter to your required value. You can jump to specific pages in the result set by setting the page url query string parameter to a value between 1 and number of pages. I.e. to get the sites overview in batches of 4 elements starting on page 2 (assuming there is at least two pages) use
https://api.siteimprove.com/v2/sites?page_size=4&page=2

Query parameters for paged resources

The standard paging parameters
Parameter Location Type Description
:page_size Query parameter (OPTIONAL) Integer. Between 1 and 1000. Default 10 Number of items on each page
:page Query parameter (OPTIONAL) Integer. Between 1 and number of pages in result set. Default 1 Page to retrieve

You will get a 404 http error response and a body with an error message, if you specify a page outside the range of pages in the result set.

 

Timestamps in responses

Timestamps in the form yyyy-mm-ddThh:mm:ss, e.g. "2014-09-01T22:13:50" refers to a timestamp in the time zone of the site. The site time zone can be read on the site resource.

Timestamps in the form yyyy-mm-ddThh:mm:ssZ, e.g. “2014-09-01T22:13:50Z” refers to a timestamp in UTC aka Zulu time and “2014-09-01T22:13:50+01:00” refers to a timestamp in UTC +1 hour.

 

Web links and Siteimprove custom relations

The _links section in each response contains hypermedia links to related resources in the API.

Some responses contain a _siteimprove section .

This section contains deep links into the Siteimprove tool suite. The webapp links into the Siteimprove web application representation for the resource in the response. The page_report links into the page report which highlights errors found on a page.

 

HTTP status codes

  • 200 : OK.
  • 201 : Accepted for processing, but the processing has not been completed.
  • 401 : Not Authenticated. Missing a valid basic authentication header.
  • 403 : Access forbidden. User not authorized to requested resource.
  • 404 : Not Found. Requested resource not found.
  • 406 : Not Acceptable. Cannot respond with content type requested in accept: header.
  • 429 : Too Many Requests. Probably above rate limit.