Skip to content

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 a message, the message also contains the same flow ID in its header and payload. This allows you to identify the request which has caused the message.

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 VehicleStateReceived message and pushes that message to you via AMQP. This message contains the same flow ID as you have received in the request’s header response. You know that the message is a direct result of your request.

Content⚓︎

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",
  "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",
  "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.
  • 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 messages 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/authorization-server-error Access token cannot be validated. 403 The access token cannot be validated because of a technical error at the authorization server.
/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/internal-server-error Internal Server Error 500

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.

Back to top