公開Web APIはどのようにバージョン管理していますか？
(lobste.rs)- 公開Web APIが Product API のような名前と
/api/v1パスを同時に使うと、API自体のセマンティックバージョンと構造がずれる可能性がある /v1/パスとmajor.minor.patchを併用すると、ルート とAPI契約が混ざり、セマンティックバージョンの最初の数字がURLに固定される- 互換性を壊す変更には新しいパスと リバースプロキシ のルートが必要になり、契約情報がURLとバージョン番号に分散する可能性がある
- 後続APIを同時に作ると既存APIは事実上
v1に縛られ、その後の互換性破壊的変更で名前とパスの意味が曖昧になる - 公開Web APIのバージョン管理において、繰り返し気になるやり方と、より良い 設計原則 を探そうとする問題意識である
厳選された技術トピックを続けて受け取りたいですか？
Telegramチャンネルをフォローしてください。 @GeekNewsJP
1件のコメント
Lobste.rs の意見
URL に
/v1/を入れるのは、実際には大きな利点のひとつ。エンドポイントを停止するまでは、利用者に API を壊さないことを強制できるからEvolving HTTP APIs と、同じ著者によるそのほかの記事も有用な助言を与えてくれる
基本的には各ルートに
/v1/、/v2/のように付けて 互換性を壊す変更 を示す。複数ホストで動く標準を定義しようとしているのでなく、公開運用 API であれば、完全な semantic versioning を行う理由はあまりないsemantic versioning は、ほかの開発者が変更ログを 20 分も読まなくても、安心して依存関係を更新できるようにするために存在するが、運用中の API では人々は新しいマイナーバージョンやバグ修正バージョンをいつ取り込むか選べない
何が互換性を壊す変更かは、文書化された挙動 を変える場合や、文書化された挙動に依存する既存クライアントを壊す場合だと考える。文書化されていない挙動の変更まで破壊的変更とみなすところもあるが、そこには多くのリスクがある
Google ではこうしている: AIP-185: API Versioning, AIP-180: Bacwards compatibility
これらの設計文書は Google の仕事の進め方にかなり特化しているように感じるが、API を設計するときの参考にしてきたし、その中のいくつかのアイデアはとても有用だった
一般に、すべての API は 互換性を壊す変更 をできるだけ減らすよう努めるべきだと思う。たとえばプロパティ名を変えたいなら、既存のプロパティをなくすより、新しい名前を重複して追加するほうがよい
ただし、the people at Buttondown do it のやり方もきれいだ。API バージョン間のマイグレーションを定義して、利用者はヘッダーで自分の API バージョンを固定でき、提供者は変更を継続的に進められるようにする
「常に新しい名前を優先する」という答えを思いつくが、クライアントが読み取り→修正→書き戻しの順序で動作し、サーバーが作成したオブジェクトの修正版を再送する場合には破綻しうる。クライアントが古いプロパティだけを更新し、新しいプロパティは無視したまま送り返してしまうことがあるからだ
その変換を挙動の割り当てにも使えそうだが、見落としていなければ、その点は扱われていなかった
理想的には、バージョンをパスに含め、新しいバージョンには追加的な性質を持たせるべきだ。そうすれば、古いバージョンの API は必要な入出力変換を経て、リクエストをより新しい API バージョンへ 再ルーティング できる
数年後に古いバージョンを誰も使わなくなれば削除でき、
/v1/パスはエラーになる以前、
Acceptヘッダーによる コンテンツネゴシエーション で API バージョニングを行う方式を少し読んだことがある。そういうやり方で API バージョニングをしたことがある人がいれば、経験を知りたい私の経験では、リソース単位のバージョニングやグローバルなバージョニングが最も直感的な方式に近かった。廃止には
DeprecationHTTP レスポンスヘッダー（RFC 9745）を使い、最終的には古いエンドポイントに410 Goneのようなレスポンスを返す組み合わせが、クライアントを新バージョンへ移行させるための妥当な方法に思えるさらに、誰かが 進化可能な API を作ったことがあるのかも本当に気になる。古いバージョンへのリクエストを内部で新しい API バージョンへのリクエストに変換し、クライアントが移行するか一定時間が過ぎたら、実際に古いバージョンを削除するというやり方のことだ