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
別々のスキーマを使用することで、クライアントが作成時に id や created_at のようなサーバー生成フィールドを設定するのを防ぎます。
ユースケース
CRUDエンドポイント設計はREST APIで最も一般的なパターンです。HTTPメソッドから操作への標準的なマッピング、適切なステータスコード、入出力スキーマの分離を理解することは、すべてのAPI設計者にとって不可欠です。このパターンは簡単なTodoアプリから複雑なエンタープライズシステムまで、事実上すべてのリソースベースのAPIに適用されます。