導入
たきの「博士〜！」
たきの「ログイン機能や会員登録ができるシステムを作りたいんですが、何から勉強すればいいのかわからないんです…」
博士「ふむ。」
博士「そんな時はREST APIを学ぶのじゃ。」
たきの「REST API…ですか？」
博士「Webアプリを作るなら避けては通れない知識じゃ。」
たきの「ぜひ教えてください！」
博士「では始めるぞ」
REST APIって何ですか？
博士「REST APIとは、URLで対象（リソース）を表現し、HTTPメソッドで操作内容を表現する設計のことじゃ。」
たきの「うーん…なんとなく難しいです…。」
博士「では、まずAPIから説明しよう。」
APIって何ですか？
たきの「そういえばAPIって何でしたっけ？」
博士「APIとは、プログラム同士が情報をやり取りするための窓口じゃ。」
例えばログイン機能では、
ユーザーが
「ログイン」ボタンを押すと、
画面は
APIに「このメールアドレスとパスワードでログインできるか確認してください」
とお願いする。
APIは
データベースを確認し、
ログインできるかどうかを画面へ返す。
画面
↓
API
↓
データベース
たきの「受付みたいな役割なんですね！」
博士「その通りじゃ。」
RESTって何ですか？
たきの「じゃあRESTって何なんですか？」
たきの「休む（Rest）ってことですか？」
博士「違うぞ」
博士「RESTは
Representational State Transfer
の略じゃ。」
博士「RESTは"休憩"ではなく、Webサービスを分かりやすく作るためのルールなんじゃ。」
博士「難しい英語は覚えなくてもよい。」
博士「URLで『何』を表し、HTTPメソッドで『何をするか』を表すという考え方だけ覚えておけば十分じゃ。」
たきの「それなら覚えられそうです！」
REST APIとHTTP APIの違い
たきの「RESTじゃないAPIもあるんですか？」
博士「もちろんじゃ。」
博士「例えばHTTP APIというものがある。」
たきの「何が違うんですか？」
博士「HTTP APIはHTTPを使っていれば自由に設計できる。」
例えば、
GET /getUserList
POST /createUser
POST /deleteUser
のようなURLでも問題ない。
一方REST APIなら、
GET /users
POST /users
DELETE /users/1
のように、
URLはリソース、
操作はHTTPメソッドで表現する。
| REST API | HTTP API |
|---|---|
| URLはリソースを表す | URLは自由 |
| HTTPメソッドで操作を表す | URLで操作を書くこともある |
| ルールが統一される | 柔軟に設計できる |
たきの「REST APIはルールが決まっているから分かりやすいんですね！」
博士「その通りじゃ。」
HTTPメソッドとは？
博士「ではHTTPメソッドを見てみよう。」
| メソッド | 何をする？ | 例 |
|---|---|---|
| GET | データを取得する | 「博士の情報を表示する」 |
| POST | 新しく登録する | 「博士のアカウントを新規登録する」 |
| PUT | データ全体を更新する | 「博士の名前・メールアドレス・電話番号をまとめて更新する」 |
| PATCH | データの一部を更新する | 「博士の名前を『たきの』に変更する」 |
| DELETE | データを削除する | 「博士のアカウントを削除する」 |
例えば、
GET /users
ユーザー一覧取得
POST /users
ユーザー登録
PATCH /users/1
ユーザー情報更新
DELETE /users/1
ユーザー削除
PUTとPUTCH
たきの「博士！」
たきの「PUTとPATCHって、どちらも更新ですよね？」
博士「その通りじゃ。」
博士「じゃが、更新の意味が違うのじゃ。」
例えば、現在の博士の情報が
{
"name": "博士",
"email": "hakase@example.com",
"TEL": "111-1111-1111"
}
だとする。
PATCH
博士「PATCHは、変更したい項目だけ送るメソッドじゃ。」
例えば、
{
"name": "たきの"
}
を送ると、
{
"name": "たきの",
"email": "hakase@example.com",
"TEL": "111-1111-1111"
}
となり、名前だけが変更される。
たきの「他の情報はそのままなんですね！」
博士「その通りじゃ。」
PUT
博士「一方PUTは、このデータが新しい状態ですとサーバーへ伝えるメソッドじゃ。」
例えば、
{
"name": "たきの",
"email": "hakase@example.com",
"phone": "090-1111-1111"
}
を送ると、
サーバーは
「博士の情報を、この内容に置き換える」
と考える。
じゃあPUTで名前だけ送ったら？
たきの「博士！」
たきの「じゃあPUTでも」
{
"name": "たきの"
}
だけ送れば、名前だけ変わるんじゃないですか？」
博士「良い質問じゃ。」
博士「実は、APIによっては名前だけ更新してくれるものもある。」
たきの「そうなんですか！」
博士「じゃが、それはAPIを作った人がそういう動きをするよう実装しているだけじゃ。」
博士「HTTPの仕様では、PUTは**『この内容でリソース全体を置き換える』**という意味なんじゃ。」
つまり、
{
"name": "たきの"
}
だけ送ると、
APIによっては
{
"name": "たきの"
}
だけが残り、
メールアドレスや電話番号が削除されたり、初期値になったりする可能性がある。
たきの「えぇ！？名前だけ変えたかったのに！」
博士「だからPUTでは、通常は新しい状態をすべて送るのじゃ。」
たきの「なるほど！」
たきの「PUTは『完成した新しいデータ』を送り、PATCHは『ここだけ直してください』とお願いするイメージなんですね！」
博士「その理解でばっちりじゃ。」
レスポンスコード
たきの「成功したかどうかはどう分かるんですか？」
博士「HTTPステータスコードを見るのじゃ。」
| コード | 意味 |
|---|---|
| 200 | 成功 |
| 201 | 作成成功 |
| 204 | 成功（返すデータなし） |
| 400 | リクエストが間違っている |
| 401 | ログインが必要 |
| 403 | 権限がない |
| 404 | 見つからない |
| 500 | サーバーエラー |
たきの「404は見たことあります！」
博士「『ページが見つからない』で有名じゃな。」
REST APIを作るときの注意点
セキュリティ
博士「ログインしていない人が管理者用のAPIを呼べたら困るじゃろ？」
たきの「大問題ですね…。」
博士「だから、ログインしている人だけが使えるようにしたり、管理者だけが実行できるようにしたりする仕組みが必要なんじゃ。」
パフォーマンス
博士「例えば会社に1万人の社員がおるとしよう。」
博士「その全員の情報を毎回一度に取得していたらどうなると思う？」
たきの「時間がかかりそうです…。」
博士「その通りじゃ。」
博士「だから、一度に必要な人数だけ取得したり、一度取得した情報は使い回したりして、サーバーの負担を減らす工夫をするのじゃ。」
たきの「必要な分だけ持ってくれば速くなるんですね！」
エラーハンドリング
博士「失敗したら」
エラー
だけ返すAPIでは原因が分からない。
例えば、
{
"message": "ユーザーが存在しません"
}
のように、
何が原因なのか分かるように返すと、利用する人も修正しやすくなる。
たきの「なるほど！エラーの理由まで教えてくれるんですね！」
バージョニング
博士「APIは一度公開すると、多くの人が利用する。」
博士「途中で大きく変更すると、今まで動いていたアプリが動かなくなることもあるんじゃ。」
だから、
/api/v1/users
/api/v2/users
のようにバージョン番号を付けることが多い。
たきの「古いアプリもそのまま使えるようになるんですね！」
博士「その通りじゃ。」
使用制限（レートリミット）
博士「APIを1秒間に何万回も呼ばれたらどうなると思う？」
たきの「サーバーが大変そうです…。」
博士「その通りじゃ。」
博士「そこで、『一定時間に利用できる回数』を決めて、サーバーを守る仕組みを作ることがある。」
たきの「いたずら対策にもなりますね！」
博士「そういうことじゃ。」
RESTful API
博士「RESTのルールをしっかり守ったAPIはRESTful APIというのじゃ。」
たきの「"〜らしい"という意味の ful が付いているんですね！」
博士「ふむ。」
博士「実際の現場では、この二つの言葉はほぼ同じ意味で使われることも多いが、RESTful APIは『RESTの設計原則に忠実である』ことを強調する表現として覚えておくとよいぞ。」
まとめ
REST APIとは、
- URLで「何（リソース）」を表す
- HTTPメソッドで「何をするか」を表す
- Webアプリで広く使われている設計方法
HTTPメソッドには、
- GET：取得
- POST：登録
- PUT：全体置き換え
- PATCH：一部更新
- DELETE：削除
がある。
また、安全で使いやすいREST APIを作るためには、
- セキュリティ
- パフォーマンス
- エラーハンドリング
- バージョニング
- 使用制限
も重要になる。
たきの「REST APIがだいぶ分かってきました！」
博士「ふむ。」
博士「次はJSON APIについて学んでみると良いぞ。」
博士「では、今日の一句」
今日の一句
API RESTに沿えば ええピーアイ