# Versionierung

> Was Versionierung bei der up4-API heute bedeutet: eine URL-Version, was X-API-Version und die api_version eines Schlüssels tun und wo Breaking Changes angekündigt werden.

Source: https://upfour.io/de/docs/api/versioning

Die API hat eine Version, `/v1`. Änderungen erscheinen innerhalb davon, und das [Änderungsprotokoll](https://upfour.io/docs/api/changelog.md) hält jede fest, auch die, die einen Client brechen können.

## Was die API heute tut

| Thema | Verhalten |
| --- | --- |
| **URL-Version** | Jede Operation wird unter `/v1` ausgeliefert. Eine andere Version und ein `/v2` gibt es nicht. |
| **Request-Header `X-API-Version`** | Wird akzeptiert. Jeder nicht leere Wert kennzeichnet die Anfrage als Anfrage der öffentlichen API, was ihr den `data`\-Umschlag gibt und bei `GET /monitors` die Cursor-Paginierung. Der Wert selbst wird nicht gelesen. |
| **`api_version` eines Schlüssels** | Jeder Schlüssel speichert eine, standardmäßig `2026-05-07`. `GET /me` gibt sie zurück. Am Verhalten ändert sich dadurch nichts. |
| **Header `Deprecation` und `Sunset`** | Die API sendet keinen von beiden. |

```bash
curl -s https://app.upfour.io/v1/me \
  -H "Authorization: Bearer $UP4_API_KEY" \
  -H "X-API-Version: 2026-05-07"
```

Der Aufruf oben verhält sich genau wie einer ohne den Header, weil eine Anfrage mit API-Schlüssel das Verhalten der öffentlichen API ohnehin bekommt.

## Wie dich Änderungen erreichen

Das Änderungsprotokoll kennzeichnet jede Änderung am Vertrag als **breaking**, **added**, **changed**, **deprecated** oder **documented** und hat einen Filter „Breaking only“. Es wird aus dem Verlauf der OpenAPI-Datei erzeugt. Behalte es im Blick, oder die [OpenAPI-Datei](https://upfour.io/api/openapi.json) selbst, für die Operationen, die du nutzt.

Beabsichtigt ist, dass eine Änderung, die Clients bricht, eine eigene Version bekommt, `/v2`, mit 12 Monaten Parallelbetrieb und den Headern `Deprecation` und `Sunset`. Das ist eine Absicht, kein Verhalten, auf das du testen kannst: Heute gibt es weder ein `/v2` noch einen solchen Header, und das Änderungsprotokoll zeigt Breaking Changes, die innerhalb von `/v1` vorgenommen wurden. Richte dich nach dem Änderungsprotokoll, nicht nach einem Header.

## Einen toleranten Client schreiben

- Ignoriere Felder der Antwort, die du nicht kennst; neue erscheinen als **added**.
- Verlass dich nicht auf die Reihenfolge der Schlüssel oder von `scopes` in `GET /me`.
- Verzweige nach `error.code`, nicht nach `error.message`. Siehe [Antworten und Fehler](https://upfour.io/de/docs/api/responses.md).
- Sichere die Operationen, die du nutzt, mit Tests ab. Ein geänderter nötiger Scope steht im Änderungsprotokoll als breaking.

## Typische Fehler

- `X-API-Version` senden, um ein altes Verhalten festzuhalten. Der Header hält nichts fest.
- Die `api_version` eines Schlüssels ändern, um eine andere Antwort zu bekommen. Eine solche Wirkung gibt es nicht.
- Auf einen `Sunset`\-Header warten, bevor du nach Entfernungen schaust. Lies das Änderungsprotokoll.
- Gegen `/v2`\-Pfade bauen. Sie existieren nicht.