Requests and responses

This section contains information about the Solaris API's behavior regarding API requests and how it responds.

Parameter acceptance

Please observe the following guidelines when making requests to the Solaris API:

• Parameter values passed to the API may not begin or end with a whitespace. This will cause the API to respond with an exception error.
• The API will ignore null values in the request body. This is particularly relevant for PATCH requests.
• The API is case-sensitive. This includes enumeration values. Supplying parameters or values with the wrong case will cause a validation error.
• If you supply a parameter to a POST or PATCH request that does not exist for the resource you wish to create or modify, then the API will ignore this parameter. See the example below: the schema of the resource to be created has the two parameters has_this_parameter1 and has_this_parameter2, but it does not have does_not_have_this_parameter. The API returns a 201 response without does_not_have_this_parameter.

Example request with nonexistent parameter:

// POST /v1/example_resource
{
  "has_this_parameter1": "Value1",
  "has_this_parameter2": "Value2",
  "does_not_have_this_parameter": "Value3"
}

Example response:

// HTTP/1.1 201 Created
{
  "id": "6d768d88f291f5744f9f30e9c6f2efd4ceml",
  "has_this_parameter1": "Value1",
  "has_this_parameter2": "Value2"
}

Pagination

Solaris recommends using pagination in API requests that would return a lot of results (e.g., retrieving customer bookings or transactions). Pagination improves the loading time for the API response by processing it in batches instead of all at once.

Endpoints that allow pagination include special pagination headers as defined in the RFC 5988 web linking standard:

• total: The total count of entries to be returned.
• per_page: The number of entries per page.

You can use the following query parameters to paginate an API request:

• page[number]: Specifies the number of pages of results to return. The default value is 1.
• page[size]: Specifies the number of objects to return on each page of results. The default value is 10, and the maximum value is 1000.

Append the pagination parameter to the request URL with the desired value as follows:

Example request using pagination:

GET /v1/<resource>/{resource_id}/<event>?page[number]=2&page[size]=15

In this example, the API will return two pages of results with 15 entries each.

Example response:

HTTP/1.1 200 OK
total: 64
per-page: 15
link: <:env/v1/<resource>/<resource_id>/<event>?page[number]=1&page[size]=15>; rel="first", ...
Content-Type: application/json
  ...

Link attribute

The example response makes use of an additional header attribute called link. Although the specification lists a wide range of uses for this field, Solaris only uses links for the first, last, prev (previous) and next pages of the response. prev and next are respectively omitted with the first and last page of the resource.

Each link in this list is followed by an optional link parameter. Solaris only uses rel to indicate relations between pages within the response. URIs in this list are generally URL-encoded, i.e., special characters such as brackets ([]) or spaces are escaped to their equivalent percent-literal notation.

Sorting

As with pagination, the Solaris API offers the option to sort the response of some GET requests by a specific property using a query parameter:

sort={name_of_property}

The API reference indicates which sorting options are available for each GET request.

The API will sort the response in ascending order by default. To sort in descending order, include a - before the property's name. See the examples below for more info:

Example request—sort bookings by recorded_at, ascending:

GET :env/v1/escrow/account/bookings?sort=recorded_at

Example request—sort bookings by recorded_at, descending:

GET :env/v1/escrow/account/bookings?sort=-recorded_at

Rate limiting

You may make 255 concurrent API calls at a time.

Endpoints that send SMS OTPs are limited to 60 SMS messages per recipient phone number per hour.

Timeouts and retries

Idle requests to the Solaris API will time out after 150 seconds. You should only retry requests after the timeout period has expired or after the API sends a response.