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 seek to be compliant with every major RFC governing HTTP(S) practices, and where there are competing standards affecting our API, we choose that which will be most intuitive and friendly to our users.
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 possibly, programmatic details specifying your issues with your request (and any possibly remedy) will be returned.
Partial-Success Responses
A number of Derapi endpoints report lists of resources, e.g., https://api.derapi.com/solar-inverters. These lists may aggregate responses from multiple backends. For these endpoints Derapi always reports success, even if one or more of the backend calls fail. For example, one of the backends may reject client's credentials, or be unavailable due to a network outage. In this case, Derapi reports responses from all other backends, and includes the name of the failing backend and a description of the problem in the errors object. An example response might look like this:
{
"solar-inverters": [
"https://api.derapi.com/solar-inverters/sma:12800016",
"https://api.derapi.com/solar-inverters/sma:12800017",
"https://api.derapi.com/solar-inverters/sma:12800024"
],
"errors":{
"solis": "Unauthorized: https://www.soliscloud.com:13333/v1/api/inverterList"
}
}
If all backend calls succeed, the error object is empty.
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:002021-01-01T00:00Z2021-01-01T00:00+0:00
Example incorrect values:
2021-01-01T00:00