OpenAPIでのCRUDエンドポイント設計

OpenAPI 3.0で適切なHTTPメソッド、リクエストボディ、レスポンスコード、パスパラメータを使用した完全なCRUD(Create、Read、Update、Delete)エンドポイントの定義方法を学びます。

API Design Basics

詳細な説明

OpenAPIでのCRUDエンドポイント

CRUD(Create、Read、Update、Delete)はREST API設計の基礎です。OpenAPIは適切なHTTPメソッド、ステータスコード、スキーマで4つの操作すべてを定義する構造化された方法を提供します。

標準CRUDパターン

paths:
  /resources:
    get:
      summary: リソースの一覧
      responses:
        "200":
          description: 成功
    post:
      summary: リソースの作成
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResource"
      responses:
        "201":
          description: 作成完了

  /resources/{id}:
    get:
      summary: リソースの取得
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: 成功
        "404":
          description: 見つかりません
    put:
      summary: リソースの更新
      responses:
        "200":
          description: 更新完了
    delete:
      summary: リソースの削除
      responses:
        "204":
          description: 削除完了

HTTPメソッドのマッピング

操作 HTTPメソッド コレクションパス アイテムパス
作成 POST /resources -
読取(一覧) GET /resources -
読取(単一) GET - /resources/{id}
更新(全体) PUT - /resources/{id}
更新(部分) PATCH - /resources/{id}
削除 DELETE - /resources/{id}

レスポンスステータスコード

各操作は適切なステータスコードを返すべきです:

  • GET(一覧): 200 OK(配列ボディ付き)
  • GET(単一): 200 OKまたは404 Not Found
  • POST: 201 Created(Locationヘッダー付き)
  • PUT/PATCH: 200 OK(更新されたリソース付き)
  • DELETE: 204 No Content(空のボディ)

リクエストとレスポンスのスキーマ

作成、更新、レスポンスで別々のスキーマを定義します:

components:
  schemas:
    CreateResource:
      type: object
      required: [name]
      properties:
        name:
          type: string
    UpdateResource:
      type: object
      properties:
        name:
          type: string
    Resource:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time

別々のスキーマを使用することで、クライアントが作成時に idcreated_at のようなサーバー生成フィールドを設定するのを防ぎます。

ユースケース

CRUDエンドポイント設計はREST APIで最も一般的なパターンです。HTTPメソッドから操作への標準的なマッピング、適切なステータスコード、入出力スキーマの分離を理解することは、すべてのAPI設計者にとって不可欠です。このパターンは簡単なTodoアプリから複雑なエンタープライズシステムまで、事実上すべてのリソースベースのAPIに適用されます。

試してみる — OpenAPI Editor & Viewer

フルツールを開く