🩹

[API設計] 良いAPI(URL)とは

に公開
API
初心者向け
O'Reilly
tech

はじめに

下記の書籍を読みました。
備忘録を書きます。

1. 短く入力しやすい URL

1-1. 必要最低限で表現する

❌ service, apiという言葉があり、一見丁寧な URL だけど、文字数が多くて入力しにくい

Not good
https://api.example.com/service/api/search/

⭕ 必要最低限の単語で、文字数が少なく入力しやすい

good
https://api.example.com/search/

2. 人間が読んで理解できる URL

2-1. 省略系の単語を使わない

❌ sv, uという言葉があるが、意味が伝わりにくい

Not good
https://api.example.com/sv/u/

⭕ 省略系を使わず、適切に伝える

good
https://api.example.com/service/users/

2-2. 単語は英語を使う

❌ 英語: product, スペイン語: productoのように勘違いが発生しにくいように英語にする
❌ ローマ字: seihinは論外

Not good
<!-- スペイン語 -->
https://api.example.com/producto/123/
<!-- 日本語 -->
https://api.example.com/seihin/123/
good
<!-- 英語 -->
https://api.example.com/product/123/

2-3. 適切な英語を使う

❌ find: あるものを探す

Not good
https://api.example.com/find/

⭕ search: ある場所において探す

good
https://api.example.com/search/

3. 大文字小文字が混在していない URL

3-1. 小文字を使う

❌ 大文字小文字が混在している

Not good
https://api.example.com/User/123

⭕ 小文字のみにする

good
https://api.example.com/users/123

4. 改造しやすい(Hackable)URL

4-1. 小文字を使う

⭕ v1がversionを表し、version 1.0が予想できる
⭕ itmes/123は、itmesの中のidが123を取得している事が予想できる
⭕ 別のitmesならitmes/234などにしたら取得出来そう

good
https://api.example.com/v1/itmes/123

5. サーバー側のアーキテクチャが反映されていない URL

5-1. 言語を隠す

❌ 言語が PHP である事が分かる

Not good
https://api.example.com/cgi-bin/get-user.php?user=100

⭕ 言語などの情報を開示しない

good
https://api.example.com/users/123

6. ルールが統一された URL

6-1. ルールを定める

❌ idの指定が URL 毎でバラバラ
❌ friends,friendで複数形と単数形が混在

Not good
https://api.example.com/friends?id=100
https://api.example.com/friend/100/message

⭕ friendsの複数形で統一
⭕ idを使わないで統一

good
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 は学びが多く気に入りました!

GitHubで編集を提案

Discussion