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