第2章.エンドポイントの設計とリクエストの形式
エンドポイント:WebAPIにアクセスするためのURI
ブラウザからのアクセスだとHTTPのGETメソッドになる
Web/スマホのクライアントアプリから該当するページに遷移したときや、ボタンの押下などのイベントに対応するWebAPIにアクセスすることで情報や機能を取得して利用する
APIとして公開する機能を設計する
APIがどのように使われるか、「ユースケース」ををきちんと考えることが重要
SQL文をただ包んでいるようなAPI設計は良く無い
セキュリティ上危険
データがどういうリレーションか理解していないと使えない
設計方法
クライアントアプリケーションの画面遷移から考える
提供する機能をリストアップする
上記二つを比較して過不足がないかを考える
リストアップした機能を全て個別のAPIとして実装せずまとめられるものはまとめる
APIエンドポイントの考え方
ログイン中のユーザー情報を取得するAPIのエンドポイントの例
https://api.example.com/v1/users/me
基本的な原則
覚えやすいURI
どんな機能なのかひと目でわかるURI
覚えやすくわかりやすいAPI設計をすることで、利用する開発者により良い開発者体験を提供できる
間違ったアクセスによりAPIを配信するサーバーに負荷をかける可能性を防げる
覚えやすいURI
短く入力しやすい
NG: htto://api.example.com/service/api/search
apiというワードがホストとパスどちらにもには必要ない
serviceというワードは特に必要ない(apiというワードがあるから充分)
人間が読んで理解できる
むやみに省略しない
国名や言語名など標準化されているものは乗っかるべき
APIでよく使われている英単語を使うべき
一般的なプログラミングの命名と似た思想
単語から機能を推測しやすい
和製英語や誤字に気を付ける
NG: http://api.example.com/sv/u/
sv, uの意味が何かしらの略語だとしてもわからない
大文字小文字が混在していない
基本的に大文字は使わない
大文字と小文字は区別されると仕様書(RFC7230)に書かれている
大文字を混ぜてでアクセスを試みた場合に404エラーを返すサービスも多い
キャメルケースは使わない(できるだけ一単語にすべき)
改造しやすい(Hacable)
例 http://api.example.com/v1/items/12345
12345のところを別の数字(ID)に書き換えれば該当するitemの情報にもアクセスできること
サーバー側のアーキテクチャが反映されていない
サーバー側で、どんなソフトを使っているか、どんな言語で実装されているか、どんなディレクトリ構成やシステム構成か、などの情報はみせることで脆弱性になる
NG: http://api.exampel.com/cgi-bin/hoge.php?user=100
APIがPHPで書かれていることがわかる→PHPの脆弱性をついた攻撃の対象になる
ルールが統一されている
利用する単語、URIの構成
NG IDをクエリパラメータから取得するルールとURIのパス名から取得する方法の両方を使う
http://api.example.com/v1/friends?id=100
http://api.example.com/v1/friend/100/message
HTTPメソッドとエンドポイント
table:よく使われるHTTPメソッド
GET リソースの取得
POST リソースの新規登録
PUT 既存のリソースの更新
DELETE リソースの削除
PATCH リソースの一部変更
HEAD リソースのメタ情報取得
必ずメソッドの役割に合った処理・機能をもたせる
HTMLのaタグは基本GETメソッドでアクセスするが、リソースの削除などの機能も持たすことはできる
POSTとPUTの違い
POSTメソッドで情報の更新・削除はしない。あくまで新規登録
URIの指定の仕方が異なる
POST: http://api.example/v1/users
作成されるリソースの上位を指定し、その中にリソースを作成する
PUT: http://api.example/v1/users/12345
更新するリソースのURIを指定し、その値を更新する
リソースが存在しない場合は新規作成になる
データの一部だけを更新したい場合にはPATCHを用いる
分かったこと
覚えやすく機能がわかりやすいURIを設計することが重要
サーバー側の都合はサーバー側で処理したうえで、わかりやすいAPIを提供する
1つのURIに対してメソッドを使い分けることで複数の機能を提供できる
1つのエンドポイントに対して異なるメソッドでアクセスすることでそれぞれのメソッドに合った操作を行うようにすることでリソースとそれをどう扱うかを分離して考えることができる