変えても壊れない API にする
API 文書は、どのアドレスに何を送ると、何が返るかを書いた説明書です。版（バージョン）は、API を変えるときに、古い使い方を壊さないための番号です。
貸出アプリは、利用者の端末に入ったまま、すぐには更新されません。API を変えても壊れない方法を学びます。
このレッスンのゴール
メモ
API の変更が、使っている人を壊すかどうかを判断できる。
重要な言葉
| ことば | いみ | れい |
|---|---|---|
| API 文書 | アドレス、メソッド、項目、番号を書いた説明書 | |
| OpenAPI | API 文書を、機械が読める形で書く決まり | |
| 版 | API の形に付ける番号 | v1, v2 |
| 互換性 | 古い使い方が、新しい API でも動くこと | |
| 破壊的な変更 | 使っている人のプログラムを動かなくする変更 | |
| 非推奨 | もうすぐやめるので、使わないでという印 |
学生が入力するセルは、このプレビューでは空白です。
API 文書は使い方の約束
API 文書には、アドレス、メソッド、送る項目、返る項目、番号を書きます。読む人が、コードを見なくても使えるようにするためです。
OpenAPI は、これを機械が読める形で書く決まりです。ツールが文書から、試せるページや、アプリ用の部品を作れます。このラボの API は、表から文書を自動で作ります。
例: 1つの操作の文書
| 項目 | 書くこと | 例 |
|---|---|---|
| アドレスとメソッド | 何を頼むか | GET /books |
| 送る項目 | 条件や本文 | year=gte.2020 |
| 返る項目 | 名前と型 | title は文字列 |
| 番号 | 起こりうる結果 | 200 と 400 |
| 認証 | 鍵が要るか | このラボでは不要 |
学生が入力するセルは、このプレビューでは空白です。
足す変更は安全で、消す変更は壊す
項目を足す変更は、たいてい安全です。古いアプリは、新しい項目を使わないだけだからです。
項目を消す、名前を変える、型を変える変更は、古いアプリを壊します。これを破壊的な変更と呼びます。
例: 変更と古いアプリ
| 変更 | 古いアプリは | 壊れるか |
|---|---|---|
| 項目を足す | 新しい項目を無視する | 壊れない |
| 項目を消す | 値が取れない | 壊れる |
| 項目の名前を変える | 古い名前で探せない | 壊れる |
| 型を数値から文字列に | 計算や比較ができない | 壊れる |
| 必須の送信項目を足す | 依頼が断られる | 壊れる |
学生が入力するセルは、このプレビューでは空白です。
ラボで、足す変更と名前を変える変更を試す
本の表に、列を1つ足します。古い依頼がそのまま通ることを見ます。
次に、year の列の名前を変えます。year を使っていた依頼が、どうなるかを見ます。順番に Run してください。
psql にパスワードを渡す
export PGPASSWORD=shopここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
本の表を作り直す
psql -h db -U shop -c "drop table if exists books; create table books (id serial primary key, title text not null, author text not null, year int not null, copies int not null default 1); insert into books (title, author, year, copies) values ('Networks in Practice', 'Mori', 2019, 3), ('Learning SQL', 'Tanaka', 2021, 2), ('Web Design Basics', 'Suzuki', 2018, 0), ('Intro to APIs', 'Kato', 2022, 5); notify pgrst, 'reload schema'"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
API 文書を取る
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
古いアプリの依頼: year を頼む
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/books?select=id,year"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
列を1つ足す
psql -h db -U shop -c "alter table books add column language text; notify pgrst, 'reload schema'"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
新しい項目が増えたのを見る
curl -s -w "\n" "http://api:3000/books?id=eq.1"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
古いアプリの依頼は、まだ通る
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/books?select=id,year"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
year の名前を published に変える
psql -h db -U shop -c "alter table books rename column year to published; notify pgrst, 'reload schema'"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
古いアプリの依頼が壊れる
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/books?select=id,year"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
よくある間違い
注意
利用者はすぐアプリを更新するから、API を変えてよいと考えがちです。端末のアプリは、何週間も古いまま動きます。消す前に、告知して、移る期間を渡します。
壊す変更は新しい版を別に出す
壊す変更をするときは、版を分けます。新しい版を /v2/ のように別のアドレスで出し、古い版も一定の期間、動かし続けます。
古い版を止める前に、非推奨と告知します。使っている人が、移る時間を持てるようにするためです。