Zum Hauptinhalt springen

Einleitung und API-Konzepte

Basis-URLs​

Die mStudio v2 API verwendet https://api.mittwald.de/v2/ als Basis-URL für alle API-Endpunkte.

Spezifikation​

Die vollständige API-Spezifikation im OpenAPI 3.0-Format findest du hier:

  1. OpenAPI 3.0-Spezifikation (maschinenlesbar)
  2. HTML-Dokumentation (menschenlesbar)

Changelog​

Änderungen an der API sind im Changelog dokumentiert. Changelog-Einträge werden automatisch am Ende eines jeden Tages generiert. Wenn du über Änderungen an der API informiert werden möchtest, kannst du den RSS-Feed abonnieren.

Authentifizierung​

Ein API-Token beziehen​

Um dich an der API zu authentifizieren, benötigst du ein API-Token. Du kannst es entweder über die mittwald mStudio Web-UI oder über die API selbst beziehen (wenn du bereits über ein anderes API-Token verfügst).

  1. In der Web-UI gehe zu deinem Benutzerprofil und wähle den Menüpunkt API-Tokens aus.

  2. Alternativ, über die API, verwende den POST/v2/users/self/api-tokens/-Endpunkt. Dieser setzt voraus, dass du ein bereits bestehendes API-Token hast:

    POST /v2/users/self/api-tokens 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 Antwort auf diese Anfrage wird ein JSON-Dokument mit einem token-Attribut enthalten. Dies ist dein API-Token.

API-Anfragen authentifizieren​

Sobald du ein API-Token erhalten hast, gibt es zwei Möglichkeiten, sich an der API zu authentifizieren:

  1. Verwende den X-Access-Token-HTTP-Header. Der Wert dieses Headers ist einfach nur das API-Token.

    GET /v2/user HTTP/1.1
    Host: api.mittwald.de
    X-Access-Token: <API_TOKEN>

  2. Verwende den Authorization-Header, und verwende das API-Token als Bearer-Token.

    GET /v2/user HTTP/1.1
    Host: api.mittwald.de
    Authorization: Bearer <API_TOKEN>

Rate-Limiting​

Die API ist auf eine bestimmte Anzahl von Anfragen pro Zeitraum begrenzt, um Missbrauch zu verhindern. Du kannst die Rate-Limiting-Einstellungen für deinen aktuellen Benutzer überprüfen, indem du die Header in der Antwort überprüfst:

  • X-RateLimit-Limit: Die maximale Anzahl von Anfragen, die du pro Zeitraum tätigen darfst.
  • X-RateLimit-Remaining: Die Anzahl der Anfragen, die noch im aktuellen Zeitraum verbleiben.
  • X-RateLimit-Reset: Die verbleibende Zeit (in Sekunden), bis der aktuelle Zeitraum endet und ein neuer beginnt.

Einige spezielle Routen sind von der Limitierung ausgenommen. Diese Routen antworten mit einem X-RateLimit-Exempt Header, der auf yes gesetzt ist.

Eventual Consistency​

Die Read Models unserer Event Sourcing-Architektur sind eventually consistent. Wenn du mehr darüber erfahren möchtest, lies den Blog-Post über Event Sourcing. Als Konsequenz kann es einen Moment dauern, bis alle Read Models nach einer POST-, PUT-, PATCH- oder DELETE-Anfrage aktualisiert sind. Dies kann dazu führen, dass eine (GET-)Anfrage, die unmittelbar nach der mutierenden Anfrage ausgeführt wird, einen Fehler verursacht, typischerweise mit einem HTTP-Statuscode wie 404 oder 403. Um diese Eventual Consistency zu handhaben, kannst du eine Kombination aus dem Antwort-Header etag und dem Anfrage-Header if-event-reached verwenden.

Um das Problem zu verhindern, kannst du die Event-ID verwenden, die im etag-Header der mutierenden Anfrage zurückgegeben wird.

etag: 276638689419853824

Diese Event-ID ist die ID des Events, das die mutierende Anfrage ausgelöst hat. Wenn dieser Header gesetzt ist, werden die verarbeitenden Services warten, bis das Event verarbeitet wurde. Nachdem das Event verarbeitet wurde, wird der Service die Anfrage ausführen und beantworten.

if-event-reached: 276638689419853824

Bitte beachte, dass eine solche Anfrage mit 412 Precondition Failed fehlschlagen kann, wenn das Event nicht innerhalb von 10 Sekunden erreicht wird.