Concepts

Pagination

The API uses cursor-based pagination. All list endpoints return data in reverse chronological order, and have the following common structure:

GET parameters

• limit: How many items to fetch, between 1 and 100
• cursor: Value of cursor_next from a previous request. If not given, it will fetch the most recent items.

Response data

• data: The received items, in a JSON array.
• has_next: Whether there are more items to fetch.
• cursor_next: Cursor to fetch the next page of items. Only present if has_next is true.

Versioning

The major version is indicated in the URL. For example https://api.akiles.app/v1 vs https://api.akiles.app/v2. The minor version is not indicated anywhere, since minor versions only do backwards-compatible changes. A client designed for API version v2.0 should work unmodified on version v2.1, provided it follows the compatibility policy outlined below.

We will release new minor versions with only backwards-compatible changes. We consider the following changes backwards-compatible:

• Adding new endpoints.
• Adding new HTTP methods to existing endpoints.
• Adding new optional fields to request objects.
• Adding new fields to response objects.
• Adding new possible values to enum fields.
• Relaxing request validation rules. For example, a field couldn’t be null before and now it can.

Keep these in mind when developing your integration. For example, when parsing API responses, ignore unknown received fields instead of erroring.

Occasionally, when backwards-incompatible changes are necessary for the healthy evolution of the platform, we will also release new major API versions. In this case, the previous major version will be supported for at least 6 months after the launch of the new major version.