Requests

Headers

As described in the Authentication page, all requests to the API must include the X-API-KEY header.

When applicable (i.e. when making any requests containing a body), requests should also contain a Content-Type header. For example Content-Type: application/json.

Clients should also send an Accept header for example Accept: application/json indicating the expected response type.

Path Parameters

In general, all entities for which access is provided via the public API support two categories of requests:

Collection Requests

Actions like listing, creating new objects, or those involving multiple objects do not require any path parameters.

Object-specific Requests

Requests for actions that are performed on specific objects, such as retrieving detailed data, partial updates, full updates, and deletion, will require a path parameter specifying the target object ID to be indicated, with this parameter required to be a positive integer.

Failing to provide this parameter will result in either a 400 ("Bad Request") or 405 ("Method Not Allowed") response, while providing an invalid value will result in one of the following errors:

• HTTP 400 ("Bad Request"): In case the provided value does not represent a valid positive integer number.
• HTTP 403 ("Forbidden"): In case the user associated with the request API Key does not have the necessary permissions to access the specified object.
• HTTP 404 ("Not Found"): In case an object matching the provided id is not found within the objects accessible to the authenticated user making the request.

Query Parameters

Some endpoints, especially GET requests for actions like listing and searching entities, will also accept a series of query parameters. The accepted parameters will be defined in the documentation for each endpoint that accepts them.

Please note that in the RoofLink public API, delete requests may also include query parameters.

Pagination

All requests that return collection-level data will have paginated responses.

The pagination is controlled using the following parameters:

Page Size

The page_size parameter indicates the number of items returned per page. Please note that the maximum number of elements per page is limited on the server side, and specifying a number of elements higher than the maximum for a given endpoint will result in the maximum number of elements being returned by the server.

This parameter is always optional, with the default and maximum values being endpoint-specific.

Page

The page parameter is a 1-indexed positive integer that indicates which response page will be sent by the server.

For example, a request resulting in 25 matching items combined with a page_size=10 will result in:

• page=1 returning items with index from 1 to 10
• page=2 returning items with index from 11 to 20
• page=3 returning items with index from 21 to 25
• page=4 and above values will result in a response with no results

This parameter is always optional, with default value set to 1.

Request Body

Most of endpoints provided in the RoofLink public API expect the body parameters to be encoded in JSON.

The only exceptions are for endpoints that are used for file uploads.

As mentioned in the Headers section, all requests containing a body are advised to include the Content-Type header.