モバイルアプリとパートナー向けAPIの進化:バージョン、互換性、廃止

要点: Webサイトはいつでも更新できますが、ユーザーの端末に入っているアプリやパートナーのシステムはそうはいきません。APIは一度出したら、呼び出し元が長い間更新しないものとして扱います。私たちのルールは次のとおりです。互換の変更は既存の版に入れ、非互換の変更には新しい版を切る。旧版は非推奨とし、呼び出し元ごとに利用量を計測する。利用量が許す段階になってから廃止する。契約はファイルにしてCIで検査する。

APIバージョンのライフサイクル図。/v1は稼働中で互換の変更だけを受け入れ、非互換の変更が必要になると/v2を切ります。その後/v1はDeprecationヘッダーとSunsetヘッダーで非推奨となり、最後は明確なエラーを返して廃止されます。下段には、アプリの版とパートナーキーごとの/v1の利用計測(利用状況が許すときだけ廃止)と、CIで前回リリースと差分比較される契約ファイル(OpenAPI)があり、新しい版以外での非互換変更は失敗になります。
図1. メジャーバージョンが稼働、非推奨、廃止へ進む流れ。廃止の判断基準はカレンダーではなく利用量です。

1.0 何が互換か

変更互換性
任意のリクエスト項目の追加、レスポンス項目の追加互換。ただしクライアントが未知の項目を無視することが前提
エンドポイントの追加互換
項目の削除や名前の変更、型の変更非互換
任意項目を必須に変更非互換
列挙値の追加クライアントが未知の値をどう扱うかによる。非互換として評価するのが無難
エラーコードや既定の並び順の変更互換扱いされがちだが、それに依存するクライアントを壊す

事故が起きやすいのは最後の2行です。私たちは最初の版から、未知の列挙値に対してはクラッシュせず代替表示をするよう、クライアントのガイドラインに明記しています。

2.0 バージョンをどこに置くか

/v1/ のようなパスに置くのがもっとも見えやすく、ログ、ゲートウェイのルーティング、キャッシュとも相性が良いので、私たちの標準です。ヘッダーに置くと見た目はすっきりしますが、デバッグ中に見落としがちです。どこに置くにせよ、版を上げるのは非互換の変更があるときだけで、製品のバージョン番号には連動させません。

同じメジャーバージョンの中で、クライアントのリリースごとに細かな振る舞いの違いが必要になることがあります。その場合はクライアントにアプリの版をヘッダーで送らせ、サーバー側で判断します。小さなAPIバージョンを次々に作るよりずっと扱いやすくなります。

3.0 契約はファイルにする

APIはOpenAPIなどの記述ファイルで定義し、リポジトリに置きます。CIは2つのことをします。変更を前回リリースの契約と差分比較し、新しい版に入っていない非互換の変更があればビルドを失敗させること。契約テストで、実装が記述と一致しているかを確認することです。

パートナー向けAPIでは、契約ファイルを開発者向けマニュアルの元にし、別の文書を並行して保守しません。別々に書かれた2つの文書は、遅かれ早かれ食い違います。

4.0 非推奨と廃止

  1. 新しい版を出すとき、旧版のレスポンスにDeprecationヘッダーとSunsetヘッダー(RFC 9745、RFC 8594)を付け、ドキュメントに廃止日を明記します。
  2. 旧版の利用量を呼び出し元ごとに計測します。どのアプリの版、どのパートナーキーがまだ呼んでいるかです。
  3. モバイルには最低サポート版を設けます。サーバーが最低版を配信し、それより古いアプリは更新を促します。
  4. 利用量が許容できる水準まで下がってから廃止します。廃止後は素っ気ない404ではなく、明確なエラーコードと更新方法の案内を返します。

廃止日はアプリストアの審査とユーザーの更新のペースを考慮して決め、パートナーには自社側での開発、テスト、リリースに必要な期間を確保します。

5.0 冪等性と再試行

モバイル回線では再試行が当たり前です。作成系のエンドポイントは冪等キーを受け付けます。クライアントが操作ごとにキーを生成し、サーバーは一定期間、同じキーに同じ結果を返します。「注文が二重に送信された」といった問題はプロトコルの段階で防げます。

アプリやパートナー向けのAPIを設計する場合や、手に負えなくなったAPIを立て直す場合は、Web・クラウド・デバイス管理をご覧いただくか、プロジェクトのご相談からご連絡ください。

参考資料

よくあるご質問

自社のWebフロントエンドだけが使うエンドポイントにも、ここまでの厳しさが必要ですか?

バックエンドと一緒にリリースし、一緒にロールバックするWebフロントエンドなら、契約チェックさえ回していれば緩めに扱えます。モバイルアプリ、ミニプログラム、外部システムなど、サーバーと足並みをそろえてリリースできないクライアントが1つでもあれば、この記事のルールに従います。

GraphQLならバージョン管理は不要ですか?

GraphQLでは版を分けず、フィールドの追加と非推奨の印付けで進化させるのが慣習ですが、本質的には同じ互換性の規律です。フィールドを削除する前に、誰がまだそれを問い合わせているかを把握する必要がある点も変わりません。

旧版はどのくらい維持すべきですか?

一般的な答えはなく、ユーザーの更新の速さとパートナーのリリース周期によります。私たちは実際の利用量で判断し、新しい版を出す時点で廃止日を告知して、呼び出し元が計画に組み込めるようにします。

内部をリファクタリングしました。公開APIも変えるべきですか?

APIは外部への約束を表すもので、内部構造を映すものではありません。サーバー側で対応付けを行い、外部の契約を変えずに保つのが、内部リファクタリングではたいてい最も安上がりです。