API のバージョンと後方互換性をどう保ちますか

互換を保つ変更と壊す変更

後方互換性とは、API を変えたあとも、前から使っている呼び出し側がそのまま動くことです。

• 互換を保つ応答に新しい項目を足す、受け取る項目に省略してよい物を足す、新しい住所を足す
• 互換を壊す項目を消す、名前を変える、型を変える (数を文字列にする など)、省略してよかった項目を必須にする、エラーの形を変える

たとえば、name を fullName に変えたいときは、いきなり置き換えず、しばらく両方を返します。

{
  "id": 7,
  "name": "山田 花子",
  "fullName": "山田 花子"
}

呼び出し側が fullName に移ったのを確かめてから、name を消します。ここで大事なのは、呼び出し側が「知らない項目が来ても無視する」作りになっていることです。そうなっていれば、足す変更で落ちません。

版の分け方

壊す変更をまとめて出すときは、版を分けます。

GET /v1/users/7
GET /v2/users/7

住所に版を入れると、見て分かりやすく、試すのも簡単です。ヘッダーで版を指定する方法は、住所をきれいに保てますが、ブラウザで開くだけでは試しにくく、キャッシュでも版の違いを考える必要があります。どちらにするかより、チームで 1 つに決めてそろえることのほうが大事です。

古い版を閉じる手順とトレードオフ

古い版は、いきなり止めません。

1. 新しい版を出し、古い版は「いつ閉じるか」を文書や応答のヘッダーで知らせます
2. 古い版への呼び出しの数を記録で見て、誰がまだ使っているかを確かめます
3. 使う人がほぼいなくなってから閉じます

スマホアプリは、利用者が更新しない限り古い版が残ります。起動のときに「この版はもう使えません。更新してください」と出せる仕組みを、最初の版から入れておくと、あとで古い API を閉じられます。

版を分けることにも弱点があります。動かす版が増えるほど、直す場所も試す場所も増えます。だから、版を上げるのは本当に壊す変更が要るときだけにし、ふだんは足す変更で進めます。社内の画面からしか呼ばない API で、画面とサーバーを同時に出せるなら、版を分けずに一緒に直すほうが軽いこともあります。

話すときは、自分が関わったサービスで項目の名前を変えた、または版を上げた例を 1 つ用意し、どう移行したかを順に話します。