API Reference

Overview

Welcome to the Derapi API Reference. Here you will find details about interacting with the API and details for each endpoint.

The API is standard REST + JSON over HTTPS fully documented with OpenAPI 3.1.

We aim to comply with all major RFCs for HTTP(S) and choose the most user-friendly standard when there are competing options for our API.

SDKs

Derapi offers SDKs to more easily integrate with Derapi APIs. Our SDKs are regularly updated.

Available APIs:

If your preferred program language is not list please contact [email protected].

Versioning

The Derapi API maintains versions in the format vYYYY-MM-DD. The current version is v2024-09-01. Version can be specified by setting the header api-version.

Errors

Derapi uses standard HTTP response codes to signal success or failure. In cases of failure, Derapi's response includes a description of the failure in JSON format.

When possible, programmatic details specifying your issues with your request (and any possibly remedy) will be returned.

See our errors page for details.

Pagination

List endpoints are paginated. Query string parameters pageSize and pageToken can be provided to control the pagination behavior; a property nextPageToken will be present in the response when there are more results to view. Responses may also include totalSize where available.

To get all results, in pseudocode:

results, nextPageToken = listOperation(pageSize)
while nextPageToken is not null:
    nextPage, nextPageToken = listOperation(nextPageToken)
    results += nextPage

Partial Update Operations

For operations with partial update semantics, Derapi uses the
PATCH verb.
The request bodies of those operations are interpreted as JSON Merge Patches.
Either the content-type application/json or the standard-specific application/merge-patch+json are accepted.

Custom formats

Currently, Derapi extends the OpenAPI 3.1 standard with a single custom format.

date-time-tz

Where the API expects or returns date times, they are specified with the custom format date-time-tz.
A date-time-tz value must specify a timezone in one of the valid ISO8601 standards.

For example:

  • 2021-01-01T00:00:00-7:00
  • 2021-01-01T00:00Z
  • 2021-01-01T00:00+0:00

Example incorrect values:

  • 2021-01-01T00:00