Introduction and API concepts
Base URLs
The mStudio v2 API uses https://api.mittwald.de/v2/
as base URL for all API endpoints.
Specification
You can find the full API specification in the OpenAPI 3.0 format here:
- OpenAPI 3.0 specification (machine-readable)
- Rendered HTML documentation (human-readable)
Authentication
Obtaining an API token
To authenticate to the API, you will need an API Token. You can obtain one either via the mittwald mStudio Web UI or via the API itself (if you already have another API token).
In the UI, go to your user profile and choose the API tokens menu item.
Alternatively, via the API, use the
/v2/signup/token/api
endpoint. This requires you to already have an existing API token:POST /v2/signup/token/api HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json
Authorization: Bearer <EXISTING_API_TOKEN>
{
"description": "My API token",
"expiresAt": "2021-12-31T23:59:59+00:00",
"roles": ["api_read", "api_write"]
}The response will contain a JSON document with a
token
key. This is your API token.
Make sure to store your API token in a secure place. It is the only way to authenticate to the API. A lost token cannot be recovered.
Authenticating requests
Once you have obtained an API token, there are two ways to authenticate to the API:
Use the
X-Access-Token
HTTP header. The value of the header is just the API token itself.GET /v2/user HTTP/1.1
Host: api.mittwald.de
X-Access-Token: <API_TOKEN>Use the
Authorization
HTTP header, providing the API token as aBearer
Token.GET /v2/user HTTP/1.1
Host: api.mittwald.de
Authorization: Bearer <API_TOKEN>
Rate Limiting
Usage of the API is rate-limited to prevent abuse. You can inspect the rate limiting for your current user by observing the headers included in each response:
X-RateLimit-Limit
: The maximum number of requests you are allowed to make per period.X-RateLimit-Remaining
: The number of requests remaining in the current period.X-RateLimit-Reset
: The remaining time (in seconds) until the current rate limit period ends and a new one begins.
Some special routes may be exempt from rate limiting. These routes will respond with a X-RateLimit-Exempt
header set to yes
.
Eventual Consistency
The read models of our event sourced architecture are eventually consistent. If you want to learn about this, have a read of the blog post about event sourcing. As a consequence, changes being made by a POST, PUT, PATCH or DELETE request may take a moment until all read models are updated. This may cause a (GET) request executed immediately after the mutating request to run into an error, typically with an HTTP status code like 404
or 403
. To handle this eventual consistency, you can use a combination of the response header etag
and the request header if-event-reached
.
To prevent the issue, you might use the event id returned in the etag
header of the mutating request.
etag: 276638689419853824
This event id might be used as the value for the if-event-reached
header of the subsequent (GET) request. If this header is set, the processing services will wait until the event is handled. After the event is handled, the service will execute and answer the request.
if-event-reached: 276638689419853824
Please note, that such a request can fail with 412 Precondition Failed
if the event is not reached within 10 seconds.