# Versionierung und Stabilität

Wie die API versioniert wird, welche Änderungen ohne eine neue Major-Version eintreffen können und wie Sie sich auf v1 festlegen.

PDF Blocks versioniert die API, damit Sie Verbesserungen übernehmen können,
ohne einen überraschenden Bruch fürchten zu müssen. Die folgenden Regeln sagen
Ihnen genau, welche Änderungen Sie gefahrlos automatisch erhalten und wie eine
inkompatible Änderung Sie erreichen würde.

## Semantische Versionierung

Die API folgt [Semantic Versioning 2.0.0](https://semver.org). Für eine
Versionsnummer `X.Y.Z` gilt:

| Teil | Name  | Bedeutung                            |
| ---- | ----- | ------------------------------------ |
| `X`  | Major | Nicht abwärtskompatible Änderungen.  |
| `Y`  | Minor | Abwärtskompatible neue Funktionen.   |
| `Z`  | Patch | Abwärtskompatible Fehlerbehebungen.  |

Die aktuelle Version der Spezifikation ist `1.18.0`. Die jeweils gültige
Version können Sie jederzeit im Feld `info.version` der
[OpenAPI-Spezifikation](/docs/api/openapi-specification) nachlesen.

## Die Major-Version `v1` im Pfad

Die **Major**-Version ist im URL-Pfad festgeschrieben: Jede Aktion liegt unter
`/v1/`, wie in `https://api.pdfblocks.com/v1/add_text_watermark`. Minor- und
Patch-Releases erscheinen an Ort und Stelle unter `/v1/`. Sie erhalten sie
automatisch und ändern dafür nie Ihre URLs. Weil inkompatible Änderungen
ausschließlich unter einer neuen Major-Version erscheinen (einem neuen
Pfadsegment), bedeutet der Verbleib auf `/v1/`, dass Sie auf einem stabilen
Vertrag bleiben.

## Was als abwärtskompatibel gilt

Innerhalb von `v1` nehmen wir ergänzende Änderungen ohne neue Major-Version
vor. Betrachten Sie alles Folgende als etwas, das jederzeit auftauchen kann,
und schreiben Sie Clients, die es vertragen:

- **Neue optionale Parameter** an einer bestehenden Aktion.
- **Neue akzeptierte Werte** für einen bestehenden Parameter: ein erweitertes
  Enum.
- **Alias-Namen für Parameter**: ein neuer Name für ein bestehendes Feld,
  wobei der alte Name weiterhin akzeptiert wird.
- **Reichhaltigere Antworten**: neue Felder in einem Antworttext oder neue
  Antwort-Header.
- **Neue Aktionen und neue Endpoints.**

Nichts davon zwingt Sie, sich auf eine Minor-Version festzulegen oder Ihren
Code zu ändern. Um kompatibel zu bleiben, ignorieren Sie Antwortfelder, die Sie
nicht kennen, statt daran zu scheitern, und gehen Sie nicht von einer festen,
vollständigen Menge an Enum-Werten aus.

## Wie inkompatible Änderungen ausgeliefert werden

Eine inkompatible Änderung, also einen erforderlichen Parameter zu entfernen
oder umzubenennen, eine Antwort auf inkompatible Weise zu ändern oder
etabliertes Verhalten zu verändern, würde ausschließlich als **neue
Major-Version unter einem neuen Pfad** erscheinen, etwa `/v2/`. Ihre
bestehenden Aufrufe unter `/v1/` funktionieren unverändert weiter, und Sie
migrieren nach Ihrem eigenen Zeitplan. Wir nehmen unter `/v1/` keine
inkompatiblen Änderungen an Ort und Stelle vor.

## Sich auf eine Major-Version festlegen

Legen Sie Ihre Integration auf die Major-Version `v1` fest, indem Sie `/v1/` in
den URLs Ihrer Anfragen belassen. Mehr Festlegung brauchen Sie nicht:
Abwärtskompatible Verbesserungen aus Minor- und Patch-Releases erhalten Sie
automatisch, während inkompatible Änderungen Ihrem Pfad fernbleiben, bis Sie
sich entscheiden, eine künftige Major-Version zu übernehmen.

Was sich in jedem Release geändert hat, verfolgen Sie im
[Änderungsprotokoll](/docs/api/changelog).