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:

1. OpenAPI 3.0 specification (machine-readable)
2. Rendered HTML documentation (human-readable)

Changelog

Changes to the API are documented in the changelog. Changelog entries are generated automatically at the end of each day. If you wand to be notified about changes to the API, you can subscribe to the RSS feed.

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).

1. In the UI, go to your user profile and choose the API tokens menu item.

2. Alternatively, via the API, use the POST/v2/users/self/api-tokens/ endpoint. This requires you to already have an existing API token:

   POST /v2/users/self/api-tokens HTTP/1.1
   Host: api.mittwald.de
   Authorization: Bearer <EXISTING_API_TOKEN>
   Content-Type: application/json
   
   {
     "description": "My API token",
     "expiresAt": "2021-12-31T23:59:59+00:00",
     "roles": [
       "api_read",
       "api_write"
     ]
   }
   See full request reference at: POST/v2/users/self/api-tokens/

   The response will contain a JSON document with a token key. This is your API token.

caution

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:

1. 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>

2. Use the Authorization HTTP header, providing the API token as a Bearer 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.