ドべ初心者のREST API 設計理解

ゴール

• POST、PUTの違いがわかる人間になる
• endpoint、header、bodyに何を持たせて何を持たせないかがわかる人間になる

これがお手本だ！！ (by ChatGPT出力)

~もしユーザー情報関連のAPIを作るとしたら~

// ユーザー情報取得API

Method: GET
Endpoint: /users/{userId}
Header:
    Authorization: Bearer {token}
    Accept: application/json
Body: なし（GETメソッドでは通常使用しない）

// ユーザー情報更新API

Method: PUT または PATCH
Endpoint: /users/{userId}
Header:
    Authorization: Bearer {token}
    Content-Type: application/json
Body:
    {
      "name": "新しい名前",
      "email": "[e-mail]"
    }

// ユーザー情報削除API

Method: DELETE
Endpoint: /users/{userId}
Header:
    Authorization: Bearer {token}
    Body: なし（DELETEメソッドでは通常使用しない）

各パラメータの違い

POST、PUTの違い

新規登録 は POST、
更新 は PUT
というだけのことです。

endpoint、header、bodyの違い（それぞれ何を持たせるか）

• endpoint

  • リソースを特定する内容を含む
  • 例えば、ユーザー関連APIの場合はユーザーを特定できる情報＝user_idをエンドポイントに含める、など
  • 例：ユーザーID、商品ID、識別ID系のもの

• header

  • APIリクエスト/レスポンスと共に送られるメタデータが含まれる
  • 例：
    • 認証情報（トークン等）
    • コンテンツの種類（Content-Type）
    • 許可されているリクエスト方法（メソッド）やオリジン（CORS設定）
    • キャッシュポリシー

• body

  • 実際にサーバーに送信されるデータが含まれる
  • 例：
    • ユーザーの作成や更新時に必要な情報（例: 名前、メールアドレス）
  • GET、DELETEメソッドの場合はbodyを使用しないことが多い

補足

エンドポイントは具体的すぎる情報を避ける。

例えば、

【ダメな例】
ユーザー取得API（GETメソッド）：/v1/user/get_user/{user_id}
ユーザー更新API（PUTメソッド）：/v1/user/update_user/{user_id}

【良い例】
ユーザー取得API（GETメソッド）：/v1/user/{user_id}
ユーザー更新API（PUTメソッド）：/v1/user/{user_id}

取得、更新はメソッド（GET、PUT）で区別できるから、どっちも同じエンドポイントの方がシンプルでいいよね、という話らしいです。