REST は名詞と動詞の組み合わせ
REST（レスト）は、Web API のアドレスと操作を決める設計の考え方です。この考え方を知っていると、初めて見る API でも、使い方の見当がつきます。
基本は、名詞のアドレスに、動詞のメソッドを組み合わせることです。大学図書館の API を例に、選び方を学びます。
このレッスンのゴール
メモ
リソースのアドレスを設計し、操作に合うメソッドを選べる。
重要な言葉
| ことば | いみ | れい |
|---|---|---|
| リソース | API が扱う「もの」 | 本、会員、貸出 |
| コレクション | 同じ種類のリソースの集まり | /books |
| 安全 | データを変えないという性質 | |
| 冪等（べきとう） | 何回送っても、結果が同じという性質 | |
| PUT | リソースを丸ごと置き換えるメソッド | |
| PATCH | リソースの一部だけを変えるメソッド |
学生が入力するセルは、このプレビューでは空白です。
アドレスは名詞にして、複数形にする
アドレスは、操作ではなく、ものの名前にします。本のコレクションは /books、7番の本は /books/7 です。
操作はメソッドが表すので、アドレスに「取る」や「消す」は入れません。コレクションは複数形にそろえると、読みやすくなります。
例: 良いアドレスと悪いアドレス
| アドレス | 評価 | 理由 |
|---|---|---|
| /books | 良い | 本のコレクション |
| /books/7 | 良い | 7番の本 |
| /members/3/loans | 良い | 3番の会員の貸出 |
| /getBook?id=7 | 悪い | 動詞が入っている |
| /deleteLoan/9 | 悪い | 消すのは DELETE の役目 |
学生が入力するセルは、このプレビューでは空白です。
メソッドが操作を決める
同じアドレスでも、メソッドが違えば、操作が違います。
GET は読み、POST は新しく作り、PUT は置き換え、PATCH は一部を変え、DELETE は消します。
例: 5つのメソッドの性質
| メソッド | 役目 | 安全 | 冪等 |
|---|---|---|---|
| GET | 読む | はい | はい |
| POST | 新しく作る | いいえ | いいえ |
| PUT | 丸ごと置き換える | いいえ | はい |
| PATCH | 一部を変える | いいえ | 場合による |
| DELETE | 消す | いいえ | はい |
学生が入力するセルは、このプレビューでは空白です。
安全と冪等で、送り直してよいかがわかる
ネットワークが切れて、答えが届かなかったとします。GET は、何度送り直してもかまいません。DELETE も、2回目は消すものがないだけです。
POST を送り直すと、本が2冊できるかもしれません。冪等かどうかは、送り直してよいかの目安になります。
このラボの API は行をフィルタで選ぶ
このラボの PostgREST は、書き方が少し違います。7番の本は /books/7 ではなく、/books?id=eq.7 です。
行の指定は、アドレスの ? の後ろのフィルタに書きます。考え方は REST と同じで、書き方だけが違います。順番に 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'"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
2番の本を、フィルタで読む
curl -s -w "\n" "http://api:3000/books?id=eq.2"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
2番の本を、REST のアドレスで頼む
curl -s -o /dev/null -w "%{http_code}\n" "http://api:3000/books/2"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
2番の貸出数を10に変える
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"copies":10}' "http://api:3000/books?id=eq.2"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
4番の本を消す（2回 Run する）
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "http://api:3000/books?id=eq.4"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
よくある間違い
注意
/deleteBook?id=7 のほうが、わかりやすいと考えがちです。でも、メソッドが GET なら、読むだけの安全な依頼に見えます。先読みするツールが GET を送ると、本が消えます。消すときは、メソッドを DELETE にします。