API設計のコツ（The Web API Good Parts）

Last updated at 2024-12-03Posted at 2024-12-03

API開発に携わる方におすすめの書籍「The Web API Good Parts」をベースに、
押さえておきたい基本的な部分をまとめました。

APIを開発している方だけではなく、APIを呼び出しているフロントエンドの方にもおすすめの1冊です。
2014年発行なので例が古かったりしますが、基本的な考えを学ぶにはベストな1冊だと個人的には思ってます！

アプリケーションの概要を把握する

API設計を行う前に、APIを利用するクライアントアプリケーションについて理解を深めましょう。

画面設計と遷移方法を整理して、APIがどんな機能を提供しなければならないか整理する
1. まず箇条書きで整理してみましょう。
  ※もしかすると１つにまとめられるAPIがあるかもしれませんが、この時点では機能整理が目的なのでまとめようとしないでOKです。

必要なデータを整理する

画面は異なっていても、必要なデータがほぼ同じというケースがあると思います。
また、機能ごとに整理しただけでは画面ごとに大量のAPIを実行する必要が発生するケースも出てくるかもしれません。
API実行回数が多いとその分ネットワークトラフィックのレイテンシーの影響を受けやすくなってしまうため、なるべく1つの画面で実行されるAPIは少ない方が好ましいです。
1でアプリケーションの概要を把握したら、必要なデータからAPIをまとめていけないか検討していきましょう。

エンドポイントを設計する

エンドポイント設計のコツ
1. エンドポイントは覚えやすく、どんな機能を持つのかURIからわかること
2. 小文字のみを利用する
3. リソースに複数形を利用する
4. 単語を繋げる必要がある場合はハイフンを利用する
ホスト名を考える
1. 主流はapi.example.com
レスポンスの内部構造を考える
1. なるべくAPIのアクセス回数が少なくなるように、APIのユースケースをきちんと考える
  1. APIがバックエンドのテーブル構造を反映する必要はない。
  2. APIはアプリケーションのインターフェースであり、DBへのアクセスインターフェースではない
2. レスポンスの内容をユーザが選べるようにする
  1. クエリパラメータで指定
  2. レスポンスグループを設計する（small/medium/large)
    1. AmazonのProduct Advertising APIがこの思想
3. なるべくフラットになるように設計する
  1. どうしても階層構造の方がわかりやすい場合のみ、階層構造をもつ
```
NG
{
    "id":123,
    "name":"taro",
    "profile":{
        "gender":"male",
        "birthday":19901124
}
```
```
OK
{
    "id":123,
    "name":"taro",
    "gender":"male",
    "birthday":19901124
}
```
4. 配列レスポンスはオブジェクトで包む
```
{
    "users":{
        "id":123,
        "name":"taro",
        "gender":"male",
        "birthday":19901124
    }
}
```

バージョン管理を考える

APIバージョン管理
1. バージョンの考え方を知る
  1. 1.2.3(メジャー、マイナー、パッチ）
    1. メジャー：後方互換性のない更新
    2. マイナー：後方互換性のある機能変更
    3. パッチ：APIに変更がないバグ修正など
2. メジャーバージョンだけをURIに含める
  1. 後方互換性を失ってもいいと判断できるほど大きな変更の場合のみバージョンを上げる
3. 更新のコツ
  1. 例えば性別（gender)を数値から文字列に変更したい場合
    1. genderは残しておいて、genderStrをレスポンスに追加する
    2. ドキュメントに、genderは廃止予定とマークしておく

その他のコツ

大量データの一部を取得するさいに、取得数と取得位置のクエリパラメータで指定する
1. 絶対位置で取得する（「このIDより前のもの」「この時刻より古いもの」など）
絞り込みパラメータ
1. 絞り込みフィールドを指定する =>users?name=ken
2. 全文検索で部分一致 => users?q=ken
クエリパラメータとパスの使い分け
1. パス：一意なリソースを表すのに必要な情報
2. クエリパラメータ：省略可能かどうか　（絞り込みのクエリパラメータは省略すると全取得）
配列のレスポンス
1. オブジェクトで包む
2. 続きがある場合は続きがあることと、そのURIやパラメータをレスポンスする
  1. hasNext, nextPageParam, nextPageToken, nextPageUriなど
巨大なIDは、文字列にした値も一緒にレスポンスする
1. id,id_str
PUT,PATCHの場合は２００とともにそうしたデータを返す
POSTの場合は２０１
DELTEは２０４
データが存在しないのは２００で空データをレスポンス（この書籍と違うところ）

APIエンドポイント例

(http://api.example.com/v1/)
[基本設計]
ユーザ一覧取得　users GET
ユーザの新規登録 users POST
特定ユーザ情報の取得 users/:id GET
ユーザ情報の更新 users/:id PUT/PATCH
ユーザ情報の削除 users/:id DELETE

「友達関連のAPI」
・友人の友達一覧取得
GET　users/:id/friends
・友人の追加
POST users/:id/friends
・友人の削除
DELETE users/:id/friends/:id (自身のID、友人のID）

「近況に関するエンドポイント」
近況の編集 updates/:id PUT
近況の削除 updates/:id DELETE
近況の投稿 updates/ POST
特定ユーザの近況の取得 users/:id/updates GET
友達の近況一覧の取得 users/:id/friends/pudates GET

検証

APIのロジックに進む前に、リクエストペイロードのチェックを行う
不正なペイロードが含まれるリクエストは無効にすること
optionalなプロパティがある場合にクライアントがタイプミスをしている場合、
クライアントが想定しない挙動になる恐れがある
レスポンス前に、レスポンスペイロードのチェックを行う
- 必須のプロパティが存在しない場合はエラー
- 定義していないプロパティが含まれる場合はレスポンスしない
- （APIの内容によっては、上記実装が必ずしも正しいとは限りません。）

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up