API Basics⚓︎
There are common rules that apply to all REST APIs within the INVERS OneAPI.
Authentication⚓︎
All INVERS REST APIs use the OAuth 2.0 protocol for authentication and authorization. For information on how to authenticate see Authentication.
Flow ID⚓︎
The flow ID identifies your request to the INVERS OneAPI. For every request, a flow ID is generated and returned in the X-INVERS-Flow-ID response header. When an API request fails, the error message will contain a flow_id property as well. If you need to contact us about a problem, providing the flow ID of the corresponding request will ensure the quickest possible resolution.
If your API request directly results in an event, the event also contains the same flow ID in its header and payload. This allows you to identify the request which has caused the event.
Example
You send the unlock-central-lock command to a vehicle. The INVERS OneAPI automatically generates a flow ID and returns it as X-INVERS-Flow-ID response header.
The vehicle unlocks its central lock and tells the INVERS OneAPI about the unlocked central lock.
The INVERS OneAPI generates a new VehicleStateRecorded event and pushes that event to you via AMQP. This event references the same flow ID as you have received in the vehicle command response. You then know that the event is a direct result of your request.
Content type⚓︎
REST APIs only accept JSON data in HTTP bodies and always return response data in JSON format. You have to include the corresponding header in your requests for them to be interpreted correctly: Content-Type: application/json.
Date and time values are expected in UTC in the following ISO 8601 compatible format: 2021-10-17T14:30:00Z
Errors⚓︎
The INVERS OneAPI uses conventional HTTP status codes to indicate the success or failure of an API request.
In general, codes in the 2xx range indicate success, codes in the 4xx indicate client errors, and codes in the 5xx range indicate an internal error within the INVERS OneAPI. There is one exception, which is the 502 response code (see third-party error).
Error response body⚓︎
For all responses in the 4xx and 5xx range the INVERS OneAPI provides a machine-readable problem type in the response body. This problem type is embedded in a “problem details” object following a predefined schema, which is defined in RFC 7807.
In such a case, the Content-Type response header is set to application/problem+json. For further differentiation of errors, you can use the returned problem type since it is usually more detailed than the HTTP status code alone. There can be multiple problem types for the same status code.
Example
In this example you can see two different problem types that have the same HTTP status code (404).
{
"type": "/problems/resource-not-found",
"type_documentation": "https://developers.invers.com/problems/resource-not-found",
"title": "The resource cannot be found.",
"status": 404,
"detail": "The vehicle with ID 'JQ7RP' cannot be found.",
"flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}
{
"type": "/problems/unknown-resource",
"type_documentation": "https://developers.invers.com/problems/unknown-resource",
"title": "The requested resource does not exist.",
"status": 404,
"detail": "The resource '/control/vecles' does not exist.",
"flow_id": "5e77e3e3-48ab-4955-8ab3-1c62339096ab"
}
The problem type object consists of the following properties:
type: A relative URI reference that uniquely identifies the problem type only in the context of the provided API.type_documentation: (Optional) A link to a page containing additional information about this specific problem type, as well as recommended actions to fix or avoid the problem.title: A short summary of the problem type.status: The HTTP status code of the response.detail: A human-readable explanation specific to this occurrence of the problem that is helpful in locating the problem and gives advice on how to proceed.flow_id: The Flow ID of the request (see above).
Best Practice
When handling errors use the type in the response body for switch-statements instead of the HTTP status code. A problem’s type always has a dedicated HTTP status code. However, there can be multiple different problem types for one single HTTP status code. Thus, handling the error based on the problem type gives you the opportunity to display more useful events to your users or within your log files.
Common problem types⚓︎
The following problems are common among all APIs within the INVERS OneAPI and therefore not documented in the API reference.
| Problem Type |
Title |
Status | Example Detail |
|---|---|---|---|
/problems/invalid-json |
The body contains invalid JSON. | 400 | The body contains invalid JSON (character 565). |
/problems/validation-error |
Validation Error | 400 | The value for property “vehicle.license_plate” must be a string. |
/problems/missing-credentials |
The credentials are missing. | 401 | The ‘Authorization’ header containing the access token is missing. |
/problems/invalid-credentials |
The credentials are invalid. | 401 | The access token is missing or not submitted correctly. |
/problems/forbidden-resource |
Accessing this resource is forbidden. | 403 | A scope required to access this resource is not granted. |
/problems/missing-permissions |
Accessing this resource is forbidden. | 403 | A permission required to access this resource is not granted. |
/problems/unknown-resource |
The requested resource does not exist. | 404 | The resource ‘/control/vecles’ does not exist. |
/problems/request-method-not-allowed |
The requested method is not allowed for the requested resource. | 405 | The request method ‘POST’ is not allowed for the resource ‘/vehicles’. |
/problems/content-length-required |
Content-Length header is required. | 411 | The HTTP request is not chunked and does not specify the Content-Length header. |
/problems/unsupported-media-type |
Media type not supported | 415 | Media type ‘text/html’ is not supported, use ‘application/json’ instead. |
/problems/too-many-requests |
Too many requests | 429 | This client has sent too many requests and is temporarily blocked. See ‘X-Rate-Limit’ headers for details. |
/problems/authorization-server-error |
Access token cannot be validated. | 500 | The access token cannot be validated because of a technical error at the authorization server. |
/problems/internal-server-error |
Internal Server Error | 500 |
Extensible enums⚓︎
Some API models have string-valued properties which are marked as x-extensible-enum using OpenAPI extensions. These properties are displayed in the API reference as extensible-enum: along with possible values.
While these properties behave very much like enums, there is one important difference: INVERS might add additional possible values to the property at a later stage. Therefore your integration must be able to handle these new “unknown” values. Adding additional values is a backwards-compatible API change which your code should handle gracefully.
When deserializing the JSON content in statically typed languages, we recommend deserializing these properties as string properties and not as enums. This allows you to handle the new (unexpected) values in your code without having to deal with serialization issues.
Concurrent updates⚓︎
Some API operations expose conflicts between concurrent update operations via PUT, POST, or PATCH by using the If-Match: <entity-tag> header. This forces the INVERS OneAPI to check whether the version of the updated entity is conforming to the requested <entity-tag>. This prevents ‘lost update’ or ‘initially created’ problems. Following RFC 7232 “HTTP: Conditional Requests”, this is provided by supporting the ETag header together with the If-Match conditional header.
You can recognize such concurrent update operations because they support the If-Match header parameter.
In order to use the update operation with the If-Match: <entity-tag> header, you have to get the <entity-tag> from a corresponding read-operation’s ETag header response. If the resource has been changed after you have received the ETag: <entity-tag> and you try to update the resource with the If-Match: <entity-tag> header, the update will fail with HTTP status 412 – precondition failed.
Tip
You are free to omit the If-Match header but this might cause ‘lost update’ or ‘initially created’ problems.
For fast scripting and if you know that there is no concurrent access, you can ignore the If-Match header. For a continuous and reliable integration, it is important to use the pattern with the If-Match header.
Weak Etags⚓︎
Normally, if you receive the ETag: <entity-tag> from a read operation, you can directly put it in the If-Match: <entity-tag> header when updating.
Some of the operations can return a weak etag instead. Weak etags are indicated by a weakness indicator W/ (see RFC 7232 Section 2.3). In this case you must use the part within the " quotes for the If-Match: <entity-tag> header.
Example
Read operation returns Etag with weakness indicator: ETag: W/"kezhmdjfkttqeimcn"
Use If-Match: kezhmdjfkttqeimcn header for update operation.