[API設計] 良いAPI(URL)とは
はじめに
下記の書籍を読みました。
備忘録を書きます。
1. 短く入力しやすいURL
1-1. 必要最低限で表現する
❌ service
, api
という言葉があり、一見丁寧なURLだけど、文字数が多くて入力しにくい
https://api.example.com/service/api/search/
⭕ 必要最低限の単語で、文字数が少なく入力しやすい
https://api.example.com/search/
2. 人間が読んで理解できるURL
2-1. 省略系の単語を使わない
❌ sv
, u
という言葉があるが、意味が伝わりにくい
https://api.example.com/sv/u/
⭕ 省略系を使わず、適切に伝える
https://api.example.com/service/users/
2-2. 単語は英語を使う
❌ 英語: product
, スペイン語: producto
のように勘違いが発生しにくいように英語にする
❌ ローマ字: seihin
は論外
<!-- スペイン語 -->
https://api.example.com/producto/123/
<!-- 日本語 -->
https://api.example.com/seihin/123/
<!-- 英語 -->
https://api.example.com/product/123/
2-3. 適切な英語を使う
❌ find: あるものを探す
https://api.example.com/find/
⭕ search: ある場所において探す
https://api.example.com/search/
3. 大文字小文字が混在していないURL
3-1. 小文字を使う
❌ 大文字小文字が混在している
https://api.example.com/User/123
⭕ 小文字のみにする
https://api.example.com/users/123
4. 改造しやすい(Hackable)URL
4-1. 小文字を使う
⭕ v1
がversion
を表し、version 1.0
が予想できる
⭕ itmes/123
は、itmes
の中のid
が123
を取得している事が予想できる
⭕ 別のitmes
ならitmes/234
などにしたら取得出来そう
https://api.example.com/v1/itmes/123
5. サーバー側のアーキテクチャが反映されていないURL
5-1. 言語を隠す
❌ 言語がPHPである事が分かる
https://api.example.com/cgi-bin/get-user.php?user=100
⭕ 言語などの情報を開示しない
https://api.example.com/users/123
6. ルールが統一されたURL
6-1. ルールを定める
❌ id
の指定がURL毎でバラバラ
❌ friends
,friend
で複数形と単数形が混在
https://api.example.com/friends?id=100
https://api.example.com/friend/100/message
⭕ friends
の複数形で統一
⭕ id
を使わないで統一
https://api.example.com/friends/100
https://api.example.com/friends/100/messages
HTTPメソッド
メソッド名 | 説明 |
---|---|
GET | リソースの取得 |
POST | リソースの新規登録 |
PUT | 既存リソースの更新 |
DELETE | リソースの削除 |
PATCH | リソースの一部変更 |
HEAD | リソースのメタ情報の取得 |
PUTメソッドとPATCHメソッドの違い
- PUTメソッド: もともとあるリソースを置き換える
- PATCHメソッド: もともとあるリソースの一部を置き換える
目的 | メソッド | エンドポイント |
---|---|---|
ユーザー一覧の取得 | GET | https://api.example.com/v1/users/ |
ユーザーの新規登録 | POST | https://api.example.com/v1/users/ |
特定ユーザー情報の取得 | GET | https://api.example.com/v1/users/:id |
ユーザーの情報の更新 | PUT/PATCH | https://api.example.com/v1/users/:id |
ユーザーの情報の削除 | DELETE | https://api.example.com/v1/users/:id |
ユーザーの友達一覧の取得 | GET | https://api.example.com/v1/users/:id/friends |
友達の追加 | POST | https://api.example.com/v1/users/:id/friends |
友達の削除 | DELETE | https://api.example.com/v1/users/:id/friends/:id |
近況の投稿 | POST | https://api.example.com/v1/updates |
近況の編集 | PUT | https://api.example.com/v1/updates/:id |
近況の削除 | DELETE | https://api.example.com/v1/updates/:id |
特定ユーザー近況の取得 | GET | https://api.example.com/v1/users/:id/updates |
友達の近況一覧の取得 | GET | https://api.example.com/v1/users/:id/friends/updates |
ページネーションについて
❌ 相対位置だと、データ数が増えるとパフォーマンスが下がる
❌ 相対位置だと、データの更新によってデータの順番がズレると取得するデータもズレる
⭕ 絶対位置でid
で検索だと、データ数が増えてもパフォーマンスは下がらない
⭕ 絶対位置でid
で検索だと、データ数が増えても取得するデータはズレない
Expiration Model (期限切れモデル)
レスポンスデータに期間を決める。期限が消えたら、再度アクセスをする
Validation Model (検証モデル)
現在保持しているキャッシュが最新であるかを確認する。データが更新された場合にのみ取得する
おわりに
Oreillyを初めて読みました。
自分には難しいと思っていましたが、そこまで難しいと感じなかったです。
Oreillyは学びが多く気に入りました!
Discussion