バージョニングと安定性
API がどのようにバージョン管理されているか、新しいメジャーバージョンなしで届く可能性がある変更、そして v1 に固定する方法について説明します。
PDF Blocks は、思いがけない破壊的変更を心配することなく改善を取り入れられるように、API をバージョン管理しています。以下のルールは、どの変更が自動的に受け取っても安全か、そして破壊的変更がある場合にどのように届くかを正確に示しています。
セマンティックバージョニング
この API は セマンティックバージョニング 2.0.0 に従います。バージョン番号 X.Y.Z について：
| パート | 名前 | 意味 |
|---|---|---|
X |
メジャー | 後方互換性のない変更。 |
Y |
マイナー | 後方互換性のある機能追加。 |
Z |
パッチ | 後方互換性のあるバグ修正。 |
現在の仕様バージョンは 1.18.0 です。最新のバージョンは、OpenAPI 仕様 の info.version フィールドから常に確認できます。
パス内のメジャーバージョン v1
メジャーバージョンは URL のパスに固定されています。すべてのアクションは https://api.pdfblocks.com/v1/add_text_watermark のように /v1/ 配下にあります。マイナーリリースとパッチリリースは、この /v1/ 配下にそのまま追加されます。これらは自動的に届くため、受け取るために URL を変更する必要は一切ありません。破壊的変更は新しいメジャーバージョン（新しいパスセグメント）のもとでのみ提供されるため、/v1/ にとどまることは、安定した契約にとどまることを意味します。
後方互換性があるとみなされるもの
v1 の範囲内では、新しいメジャーバージョンを伴わない追加的な変更を行います。以下はすべて、いつでも現れる可能性があるものとして扱い、それらを許容できるクライアントを実装してください。
- 既存のアクションへの新しいオプションパラメーターの追加。
- 既存のパラメーターに対する新しく受け付けられる値。列挙型の拡張です。
- パラメーターのエイリアス。既存のフィールドに新しい名前が付き、古い名前も引き続き使用できます。
- より豊富なレスポンス。レスポンスボディへの新しいフィールドや、新しいレスポンスヘッダーの追加です。
- 新しいアクションと新しいエンドポイント。
これらはいずれも、マイナーバージョンを固定したりコードを変更したりする必要はありません。互換性を保つには、認識できないレスポンスフィールドがあってもエラーにせず無視してください。また、列挙型の値の一覧が固定的かつ網羅的であると想定しないでください。
破壊的変更がどのように届くか
破壊的変更（必須パラメーターの削除や名前変更、レスポンスの互換性のない変更、既存の挙動の変更など）は、/v2/ のような新しいパスのもとでの新しいメジャーバージョンとしてのみ提供されます。既存の /v1/ への呼び出しはそのまま変わらず動作し続け、移行は自分のペースで行えます。/v1/ 配下でその場で破壊的変更を行うことはありません。
メジャーバージョンに固定する
リクエスト URL に /v1/ を保つことで、統合を v1 メジャーバージョンに固定できます。必要な固定はそれだけです。後方互換性のあるマイナー・パッチの改善は自動的に受け取りつつ、将来のメジャーバージョンを自ら採用するまで、破壊的変更はあなたのパスに影響しません。
各リリースでの変更内容は変更履歴で確認できます。