データベースを見ないアプリ
社内ヘルプデスクのアプリは、まだ片付いていない問い合わせを、スマホの画面に一覧で出します。このアプリは、データベースにつながっていません。
アプリは、小さなサーバーに Web リクエストを送ります。サーバーがクエリを実行し、行を返します。
このサーバーが Web API です。今使っているアプリの多くは、この形でデータとやり取りしています。
このレッスンのゴール
メモ
HTTP で、行を読み書きできる。
重要な言葉
| ことば | いみ | れい |
|---|---|---|
| API | あるプログラムが別のプログラムにデータを頼む方法 | |
| エンドポイント | 1つの表や操作の Web アドレス | /tickets |
| HTTP メソッド | リクエストの動詞。読む、足す、変える、消す | GET |
| JSON | 行を、リストと名前と値の組で書いたテキスト | |
| ステータスコード | リクエストの結果を表す番号 | 404 |
| フィルタ | どの行を返すかを選ぶ、アドレスの中のテスト | status=eq.open |
学生が入力するセルは、このプレビューでは空白です。
API は表を Web に出す
このラボでは、PostgREST というツールが、表を Web アドレスにします。/tickets は、tickets という表です。
curl でリクエストを送ります。サーバーは、行を JSON で返します。角括弧の中に項目が並び、1行ずつが波括弧で囲まれます。
まず、データベースのクライアントの psql で、ヘルプデスクの表を作ります。順番に Run してください。
psql にパスワードを渡す
export PGPASSWORD=shopここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
最初からやり直す
psql -h db -U shop -c "drop table if exists tickets"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
tickets 表を作る
psql -h db -U shop -c "create table tickets (id serial primary key, title text not null, status text not null default 'open', priority int not null)"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
問い合わせを4件足す
psql -h db -U shop -c "insert into tickets (title, status, priority) values ('Printer jams', 'open', 2), ('No wifi in room 4', 'open', 3), ('Reset a password', 'closed', 1), ('Laptop will not boot', 'open', 3)"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
API に読み直させる
psql -h db -U shop -c "notify pgrst, 'reload schema'"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
表の全部を読む
curl -s -w "\n" "http://api:3000/tickets?order=id"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
アドレスで行を選ぶ
? から後ろがフィルタで、WHERE のようなものです。status=eq.open は、status が open に等しいという意味です。priority=gte.3 は、priority が3以上という意味です。
select=id,title は列を選びます。order=priority.desc は並べ替えます。limit=2 はリストを切ります。& でつなぎます。
アドレス全体をダブルクォートで囲みます。囲まないと、シェルが & を読んでしまいます。
未対応の問い合わせだけ
curl -s -w "\n" "http://api:3000/tickets?status=eq.open&order=id"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
急ぎのものを、2列だけ
curl -s -w "\n" "http://api:3000/tickets?priority=gte.3&select=id,title&order=id"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
一番急ぎの2件
curl -s -w "\n" "http://api:3000/tickets?order=priority.desc,id&limit=2"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
例: SQL と HTTP を並べる
| SQL | HTTP メソッド | アドレスと本文 |
|---|---|---|
| SELECT ... WHERE | GET | /tickets?status=eq.open |
| INSERT INTO | POST | /tickets と、新しい行の JSON |
| UPDATE ... WHERE | PATCH | /tickets?id=eq.1 と、変更の JSON |
| DELETE ... WHERE | DELETE | /tickets?id=eq.3 |
学生が入力するセルは、このプレビューでは空白です。
POST、PATCH、DELETE で変える
行を足すには、JSON を POST します。行を変えるには、変更を PATCH します。行を消すには、DELETE を送ります。
SQL と同じで、アドレスのフィルタが、触る行を決めます。フィルタのない PATCH や DELETE は、全部の行を触ってしまいます。
サーバーは、結果をステータスコードで知らせます。
問い合わせを足して、返事を見る
curl -s -w "\n%{http_code}\n" -X POST -H "Content-Type: application/json" -H "Prefer: return=representation" -d '{"title":"Monitor flickers","priority":2}' "http://api:3000/tickets"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
1番を完了にする
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"status":"closed"}' "http://api:3000/tickets?id=eq.1"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
3番を消す
curl -s -o /dev/null -w "%{http_code}\n" -X DELETE "http://api:3000/tickets?id=eq.3"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
ない99番を完了にする
curl -s -o /dev/null -w "%{http_code}\n" -X PATCH -H "Content-Type: application/json" -d '{"status":"closed"}' "http://api:3000/tickets?id=eq.99"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
データベースが断る行
curl -s -w "\n%{http_code}\n" -X POST -H "Content-Type: application/json" -d '{"priority":1}' "http://api:3000/tickets"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
よくある間違い
注意
2で始まる番号が返れば、思った通りになったと考えがちです。番号が言うのは、サーバーが受け取って理解したことだけです。何にも合わないフィルタの PATCH でも、204 が返ります。表を読み直して確かめます。
表をもう一度読む
curl -s -w "\n" "http://api:3000/tickets?order=id"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
ない表を頼む
curl -s -w "\n%{http_code}\n" "http://api:3000/nothing"ここでは表示のみで、実行されません。無料アカウントを作成すると、実行ボタンで自分のラボのターミナルに入力できます。
例: ステータスコードを読む
| 番号 | 意味 | このレッスンで見たもの |
|---|---|---|
| 200 | OK。行を返した | 表を読んだとき |
| 201 | 新しい行を作った | 問い合わせを足した POST |
| 204 | 終わった。返すものはない | PATCH と DELETE |
| 400 | リクエストが間違っているか、決まりに反する | title のない問い合わせ |
| 404 | その表やアドレスはない | /nothing を頼んだとき |
学生が入力するセルは、このプレビューでは空白です。