Open2

API設計で普段気をつけていることを言語化する

occhiocchi

  • 明確なエンドポイント設計

    • リソースベース：エンドポイントはリソースに基づいて設計します。例えば、ユーザー情報を取得するエンドポイントは /users、特定のユーザー情報を取得するエンドポイントは /users/{id} のようにします。

  • HTTPメソッドの適切な使用

      GET：データの取得
  POST：新しいリソースの作成
  PUT：既存リソースの全体的な更新
  PATCH：既存リソースの部分的な更新
  DELETE：リソースの削除

  • ステータスコードの適切な使用

    • 代表的なものを以下に列挙する。
      • 200 OK：リクエストが成功した場合
      • 201 Created：新しいリソースが作成された場合
      • 204 No Content：リクエストが成功したが返すデータがない場合
      • 400 Bad Request：リクエストが不正である場合
      • 401 Unauthorized：認証が必要な場合
      • 403 Forbidden：リクエストが禁止されている場合
      • 404 Not Found：リソースが見つからない場合
      • 500 Internal Server Error：サーバー側のエラーが発生した場合

  • リクエストとレスポンスの設計

    • リクエストおよびレスポンスフォーマットは一貫性を保つ。基本的にJSONを使用する。
      • データの構造はできる限りフラットにする。
    • エラーメッセージ：エラーメッセージは詳細で、ユーザーにとって理解しやすい形式にする。
        {
    "error": "Invalid input",
    "details": "Email is required"
  }

  • Open APIの記述や、curlコマンド実行例などの、ドキュメント整備を行うこと。

  • パフォーマンス面に関して、必要であればAPIのレート制限やレスポンスデータのキャッシングを行う。

    • キャッシュの例として、Cache-Controlヘッダーによるクライアントサイドでのキャッシングがあったりする。