API のバージョニング — 変えられないものを、どう変えるか
レスポンスから使っていないフィールドを1つ消した。翌日、古いアプリが全部落ちた。自分が使っていないことと、誰も使っていないことは違う。
この記事の進み方
What — 何が「壊す変更」なのか
API の変更には、壊すものと壊さないものがあります。この線引きを知らないと、どちらか分からないまま出すことになります。
古い利用者が、コードを変えずに動き続ける変更。
レスポンスに項目を足す
{ id, name, price }
→ { id, name, price, sku }
任意のパラメータを足す
GET /products
→ GET /products?sort=price
新しいエンドポイントを足す- 古い利用者
- 動き続ける
- 予告
- 不要
- バージョン
- 上げなくてよい
- –ただし「未知の項目を無視する」実装であることが前提。厳格に検証する利用者は落ちる。
- –その前提を、API の文書に明記しておく。
判断の基準は「古い利用者のコードが、そのまま動き続けるか」。自分にとって自然な整理が、相手にとっては破壊になる。
- 後方互換
- 古い利用者が、変更後もそのまま動き続けること。
- 破壊的変更
- 後方互換を失う変更。利用者側の修正が必要になる。
- 非推奨
- まだ動くが、将来消す予定であることを示す状態。
- サンセット
- 提供を終了すること。日付を予告してから行う。
- 寛容な読み取り
- 知らない項目を無視し、必要な項目だけを読む実装方針。
「誰も使っていない」は、確認できないことが多い
冒頭の事故の核心はここです。
自分が見える範囲（自社の Web、管理画面）は調べられます。しかし次は調べられません。
- 過去に配布したモバイルアプリ
- 利用者が書いた連携スクリプト
- 取引先が作ったシステム
- 誰かのブラウザに残っているタブ
「使われていないことを証明する」のは、ほぼ不可能です。できるのは「使われている証拠を探す」ことだけです。
Why — API は、出した瞬間に自分のものではなくなる
相手のリリース速度は、こちらより遅い
Web なら、リロードすれば新しいコードが動きます。モバイルアプリは違います。
- 審査に数日
- 利用者が更新するまで数週間〜数か月
- 更新しない利用者が一定数、永久に残る
取引先のシステムはさらに遅い。改修の予算と工数を確保するところから始まります。
こちらが1日で出せる変更を、相手が取り込むのに半年かかる。 この非対称さが、API の変更を難しくしています。
利用状況は、測っていなければ分からない
「その項目を誰が読んでいるか」は、レスポンスを返す側からは見えません。
分かるのは「そのエンドポイントを誰が叩いたか」までです。返した JSON のどの項目を使ったかは、相手の中の話です。
だから、項目単位の削除は特に危険です。エンドポイントの利用は測れても、項目の利用は測れません。
- 1エンドポイント
- 2パラメータ
- 3レスポンスの項目
アクセスログで分かるのはエンドポイントまで。項目を使っているかは相手の中の話で、こちらからは見えない。
バージョンを増やすと、保守が倍になる
「壊すならバージョンを上げればよい」は正しいのですが、v1 と v2 を両方動かし続けることになります。
- 不具合の修正を両方に入れる
- テストも両方
- 内部の実装が分岐していく
バージョンは無料ではありません。 増やすほど、変更のたびの手間が増えます。
だから第一の選択は「バージョンを上げずに済む形にできないか」です。
演習 — まず自分で判断する
次のうち、後方互換を壊さない変更はどれですか?
レスポンスから項目を1つ消したい。最初にやることは何ですか?
読み終わりましたか?
読了にすると、これを前提とする記事がロードマップで開放されます。