API設計標準

27.1. RESTful APIルール

27.1.1. URLネーミング

• 小文字とハイフン（-）のみ使用します。アンダースコア（_）とcamelCaseは使用しません。
• リソース名は複数形を使用します。
• URLの末尾にスラッシュ（/）を含めません。

区分	正しい例	誤った例
複数形	/api/users	/api/user
ハイフン	/api/user-profiles	/api/user_profiles
小文字	/api/users	/api/Users

27.1.2. HTTPメソッド

メソッド	用途	例	レスポンスコード
GET	リソース照会	GET /api/users	200
POST	リソース作成	POST /api/users	201
PUT	リソース全体修正	PUT /api/users/1	200
PATCH	リソース部分修正	PATCH /api/users/1	200
DELETE	リソース削除	DELETE /api/users/1	204

27.1.3. URL階層構造

リソース間の関係はURLパスで表現します。

GET /api/users/{userId}/orders          # 特定ユーザーの注文一覧
GET /api/users/{userId}/orders/{orderId}  # 特定ユーザーの特定注文

• ネストは2段階までのみ許容します。
• 3段階以上のネストが必要な場合、クエリパラメータを使用します。

---

27.2. リクエスト/レスポンス形式

27.2.1. 標準レスポンス構造

単一リソースレスポンス：

{
  "id": 1,
  "name": "田中太郎",
  "email": "user@tienipia.com",
  "createdAt": "2026-02-28T10:30:00"
}

27.2.2. 一覧レスポンス（ページネーション）

{
  "content": [
    {
      "id": 1,
      "name": "田中太郎",
      "email": "user@tienipia.com"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 150,
  "totalPages": 8
}

27.2.3. ページネーションパラメータ

パラメータ	説明	デフォルト値
page	ページ番号（0から開始）	0
size	ページサイズ	20
sort	ソート基準	未指定時はデフォルトソート

GET /api/users?page=0&size=20&sort=createdAt,desc

27.2.4. 日時形式

• ISO 8601形式を使用します：2026-02-28T10:30:00
• タイムゾーンが必要な場合：2026-02-28T10:30:00+09:00

---

27.3. エラーコード体系

27.3.1. HTTPステータスコード

コード	意味	使用基準
200	OK	照会、修正成功
201	Created	リソース作成成功
204	No Content	削除成功
400	Bad Request	入力値バリデーション失敗
401	Unauthorized	認証が必要
403	Forbidden	権限不足
404	Not Found	リソースなし
409	Conflict	リソース競合（重複等）
500	Internal Server Error	サーバー内部エラー

27.3.2. カスタムエラーコード

HTTPステータスコードとは別にカスタムエラーコードを使用して、詳細なエラーを区別します。

{プレフィックス}{連番}

プレフィックス	ドメイン	例
C	共通	C001（不正な入力）
U	ユーザー	U001（ユーザーなし）
A	認証	A001（トークン期限切れ）
O	注文	O001（注文なし）

27.3.3. 標準エラーレスポンス形式

{
  "code": "U001",
  "message": "ユーザーが見つかりません。",
  "timestamp": "2026-02-28T10:30:00"
}

入力バリデーションエラー時にはフィールドごとの詳細情報を含めます。

{
  "code": "C001",
  "message": "不正な入力値です。",
  "timestamp": "2026-02-28T10:30:00",
  "errors": [
    {
      "field": "email",
      "value": "invalid-email",
      "reason": "正しいメールアドレス形式ではありません。"
    }
  ]
}

---

27.4. APIドキュメント

27.4.1. SpringDoc適用

すべてのAPIプロジェクトはSpringDoc（OpenAPI 3.0）を適用し、Swagger UIを提供します。

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.8.4</version>
</dependency>

# application.yml
springdoc:
  swagger-ui:
    path: /swagger-ui.html
  api-docs:
    path: /v3/api-docs

27.4.2. APIアノテーション

ControllerとDTOにOpenAPIアノテーションを適用します。

@RestController
@RequestMapping("/api/users")
@Tag(name = "ユーザー", description = "ユーザー管理API")
public class UserController {

  @Operation(summary = "ユーザー照会", description = "IDでユーザーを照会します。")
  @ApiResponses({
      @ApiResponse(responseCode = "200", description = "照会成功"),
      @ApiResponse(responseCode = "404", description = "ユーザーなし")
  })
  @GetMapping("/{id}")
  public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
    return ResponseEntity.ok(userService.findById(id));
  }
}

27.4.3. ドキュメント化原則

• すべての公開APIに @Operation アノテーションを含めます。
• リクエスト/レスポンスDTOにフィールド説明を含めます。
• Swagger UIは開発/ステージング環境でのみ有効化し、プロダクションでは無効化します。