The Saveris 2 API is organized around REST. Our API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. We use built-in HTTP features like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We allow you to interact securely with our API from any HTTP client using a secret token. JSON is returned by all API responses, including errors.
The Saveris 2 API uses JSON Web Tokens (JWT) for authentication. This approach provides a way for clients to authenticate every request without having to maintain a session or repeatedly pass login credentials to the server.
Before you can start using Saveris 2 API, you have to create your personal JWT. Login to your Saveris account and go to the API token page. Authenticate your account when using the API by including your JWT into every request. We expect a HTTP Authorization request header:
Authorization: Bearer <your token>
Saveris 2 API uses conventional HTTP response codes to indicate the
success or failure of an API request. In general, codes in the
2xx
range indicate success, codes in the
4xx
range indicate an error that failed given the information provided
(e.g., a required parameter was omitted, a charge failed, etc.), and
codes in the
5xx
range indicate an error with Saveris servers.
| 200 - OK | Everything worked as expected. |
|---|---|
| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 - Unauthorized | The request wasn't accepted. This can occur on different reasons: • JWT scheme expected: Expected authorization scheme is JWT (Bearer). Add HTTP Authorization header. • API token invalid: The token is invalid. Use the mandant's current token. • API Token expired: The expiration date of the token has expired. Please create a new token. • API Token unknown: The token is unknown. Use the mandant's current token. • Mandant unknown: The mandant is unknown. Use the mandant's current token. |
| 402 - Payment required | The parameters were valid but the request failed: • Feature 'API' expired: Your feature for API calls is expired. Please order new licence. • No API calls left: Your contingent for API calls is depleted. Please order new one. |
| 404 - Not Found | The requested resource doesn't exist. |
| 429 - Too Many Requests | Too many requests hit the API too quickly. |
| 500 - Server Errors | Something went wrong on server-side. |
In addition to the HTTP status codes, we provide details about errors in the body of the response in the following format:
{
"apiCallsLeft": 19999,
"version": "1.0.0",
"httpStatusCode": 500,
"errorCode": 20100,
"message": "Measuring point id(s) unknown [xxxxx]",
"description": "The measuring point id(s) is/are unknown.",
"timestamp": "20160101T12:00:00:00Z"
}The Saveris 2 API is released in versions using Semantic Versioning. A version number is build up using this pattern: MAJOR.MINOR.PATCH:
Every API request reveals the version of the responding API implementation as part of its JSON response. The MAJOR version number (v1) is also part of the URL. A new version of the API with incompatible changes will be published on a new URL. The old URL will be valid for a transitional period.
The response structure for each API call will be in the JSON format.
{
"apiCallsLeft": 19999,
"version": "1.0.0",
"somethingElse" : ""
}You'll always get the version number and the remaining API calls in the current billing interval. Please see TODO.
| Date |
Every time we provide a timestamp, it is provided as coordinated
universal time (UTC)
and formatted according ISO-8601:
yyyy-MM-ddThh:mm:ssZ
In a request, a timestamp is expected in the same way. |
|---|---|
| Decimal | '.' is always used and expeced as a decimal separator. |
Please insert your API token before testing the interface.