API仕様書の読み方

API仕様書とは

API仕様書の構成

よくある構成要素

HTTPメソッドの使い分け

【サンプル】API仕様書の実例

基本情報

ユーザー管理APIのサンプル仕様書です。以下の基本情報から始まります。

API-001：ユーザー登録

概要：新規ユーザーを登録するAPI

エンドポイント：POST /users

認証：不要

リクエストヘッダー：

リクエストボディ：

リクエスト例：

{
  "email": "user@example.com",
  "password": "Password123",
  "name": "山田太郎",
  "phone": "03-1234-5678"
}

レスポンス（成功時：201 Created）：

{
  "id": 12345,
  "email": "user@example.com",
  "name": "山田太郎",
  "created_at": "2024-01-15T10:30:00+09:00"
}

エラーレスポンス：

{
  "error": {
    "code": "EMAIL_EXISTS",
    "message": "このメールアドレスは既に登録されています"
  }
}

API-002：ユーザー情報取得

概要：指定したユーザーの情報を取得するAPI

エンドポイント：GET /users/{id}

パスパラメータ：

認証：必要

リクエストヘッダー：

レスポンス（成功時：200 OK）：

{
  "id": 12345,
  "email": "user@example.com",
  "name": "山田太郎",
  "phone": "03-1234-5678",
  "created_at": "2024-01-15T10:30:00+09:00",
  "updated_at": "2024-02-01T15:00:00+09:00"
}

エラーレスポンス：

API-003：ユーザー一覧取得

概要：ユーザー一覧を取得するAPI（ページング対応）

エンドポイント：GET /users

クエリパラメータ：

リクエスト例：GET /users?page=2&per_page=10&sort=name&order=asc

レスポンス（成功時：200 OK）：

{
  "data": [
    {
      "id": 12345,
      "email": "user1@example.com",
      "name": "田中太郎"
    },
    {
      "id": 12346,
      "email": "user2@example.com",
      "name": "鈴木花子"
    }
  ],
  "pagination": {
    "total": 100,
    "per_page": 10,
    "current_page": 2,
    "total_pages": 10
  }
}

HTTPステータスコードの意味

API仕様書を読むときのポイント

1. エンドポイントを確認する

• ベースURLは何か
• パスはどうなっているか
• パスパラメータはあるか

→ これを確認しないと、どのURLにリクエストを送ればよいか分かりません

2. リクエストを確認する

• 必須パラメータは何か
• 型は何か（string/integer/boolean）
• 制約は何か（文字数、形式）

→ リクエストを間違えるとAPIはエラーを返します

3. レスポンスを確認する

• どんなデータが返ってくるか
• ネストした構造はどうなっているか
• 配列かオブジェクトか

→ レスポンスの形を知らないと、返ってきたデータを処理できません

4. エラーを確認する

• どんなエラーが返ってくるか
• エラーコードは何か
• エラーメッセージはどこにあるか

→ エラーハンドリングをしないと、予期しない動作が発生します

APIテストツールの活用

Postmanでのテスト例

1. メソッドを選択（GET/POST等）
2. URLを入力
3. ヘッダーを設定（Authorization等）
4. Bodyを入力（POST/PUT等）
5. Sendで実行
6. レスポンスを確認

よくある疑問

【実践】API仕様書からSpring Bootで実装する

サンプルのユーザー登録API仕様書から、Spring Bootで実装してみましょう。

ステップ1：リクエストDTOを作る

API仕様書の「リクエストボディ」からDTOクラスを作成します。

import javax.validation.constraints.*;

// API仕様書の「リクエストボディ」から作成
public class UserRegistrationRequest {

    // email - string, 必須, メール形式、256文字以内
    @NotBlank(message = "メールアドレスを入力してください")
    @Email(message = "メールアドレスの形式が正しくありません")
    @Size(max = 256)
    private String email;

    // password - string, 必須, 8文字以上
    @NotBlank(message = "パスワードを入力してください")
    @Size(min = 8, max = 64, message = "パスワードは8文字以上で入力してください")
    private String password;

    // name - string, 必須, 100文字以内
    @NotBlank(message = "氏名を入力してください")
    @Size(max = 100)
    private String name;

    // phone - string, 任意, ハイフン含む15文字以内
    @Size(max = 15)
    private String phone;

    // getter/setter は省略
}

ステップ2：レスポンスDTOを作る

API仕様書の「レスポンス」からDTOクラスを作成します。

import java.time.LocalDateTime;

// API仕様書の「レスポンス（成功時）」から作成
public class UserRegistrationResponse {
    private Long id;
    private String email;
    private String name;
    private LocalDateTime createdAt;

    // コンストラクタ
    public UserRegistrationResponse(User user) {
        this.id = user.getId();
        this.email = user.getEmail();
        this.name = user.getName();
        this.createdAt = user.getCreatedAt();
    }

    // getter は省略
}

ステップ3：エラーレスポンスを作る

API仕様書の「エラーレスポンス」からエラー用のクラスを作成します。

// エラーレスポンスの構造
public class ApiError {
    private ErrorDetail error;

    public ApiError(String code, String message) {
        this.error = new ErrorDetail(code, message);
    }

    // getter
    public ErrorDetail getError() { return error; }

    // 内部クラス
    public static class ErrorDetail {
        private String code;
        private String message;

        public ErrorDetail(String code, String message) {
            this.code = code;
            this.message = message;
        }

        // getter
    }
}

// エラーコードをEnumで管理
public enum ErrorCode {
    INVALID_REQUEST("リクエスト形式が不正です"),
    INVALID_EMAIL("メールアドレスの形式が正しくありません"),
    INVALID_PASSWORD("パスワードの形式が正しくありません"),
    EMAIL_EXISTS("このメールアドレスは既に登録されています"),
    INTERNAL_ERROR("システムエラーが発生しました");

    private final String message;

    ErrorCode(String message) {
        this.message = message;
    }

    public String getMessage() { return message; }
}

ステップ4：コントローラーを作る

API仕様書の「エンドポイント」と「メソッド」からコントローラーを作成します。

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;

@RestController
@RequestMapping("/api/v1")  // ベースURL
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    // POST /users - ユーザー登録
    @PostMapping("/users")
    public ResponseEntity registerUser(
            @Valid @RequestBody UserRegistrationRequest request) {

        try {
            User user = userService.register(request);
            // 成功時: 201 Created
            return ResponseEntity
                .status(HttpStatus.CREATED)
                .body(new UserRegistrationResponse(user));

        } catch (EmailAlreadyExistsException e) {
            // 409 Conflict: メールアドレス重複
            return ResponseEntity
                .status(HttpStatus.CONFLICT)
                .body(new ApiError("EMAIL_EXISTS", e.getMessage()));
        }
    }

    // GET /users/{id} - ユーザー情報取得
    @GetMapping("/users/{id}")
    public ResponseEntity getUser(@PathVariable Long id) {
        return userService.findById(id)
            .map(user -> ResponseEntity.ok(new UserResponse(user)))
            .orElse(ResponseEntity.notFound().build());  // 404
    }

    // GET /users - ユーザー一覧取得（ページング対応）
    @GetMapping("/users")
    public ResponseEntity> getUsers(
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "20") int perPage,
            @RequestParam(defaultValue = "created_at") String sort,
            @RequestParam(defaultValue = "desc") String order) {

        Page users = userService.findAll(page, perPage, sort, order);
        return ResponseEntity.ok(new PagedResponse<>(users));
    }
}

ステップ5：バリデーションエラーのハンドリング

Spring Bootの@Validアノテーションによるバリデーションエラーを処理します。

import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {

    // バリデーションエラー → 400 Bad Request
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity handleValidationError(
            MethodArgumentNotValidException ex) {

        String message = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .findFirst()
            .map(error -> error.getDefaultMessage())
            .orElse("入力エラー");

        return ResponseEntity
            .badRequest()
            .body(new ApiError("INVALID_REQUEST", message));
    }

    // その他の例外 → 500 Internal Server Error
    @ExceptionHandler(Exception.class)
    public ResponseEntity handleInternalError(Exception ex) {
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ApiError("INTERNAL_ERROR", "システムエラーが発生しました"));
    }
}

API仕様書とコードの対応表

フロントエンドからのAPI呼び出し例

// ユーザー登録API呼び出し
async function registerUser(formData) {
  try {
    const response = await fetch('/api/v1/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(formData)
    });

    if (response.status === 201) {
      // 成功
      const data = await response.json();
      console.log('登録成功:', data);
      return { success: true, data };
    } else {
      // エラー
      const error = await response.json();
      console.log('エラー:', error.error.code, error.error.message);
      return { success: false, error: error.error };
    }
  } catch (e) {
    return { success: false, error: { code: 'NETWORK_ERROR', message: '通信エラー' } };
  }
}

関連ドキュメント

• 設計書・仕様書の読み方 - 設計書全般の読み方
• 要件定義書の読み方 - 要件定義から仕様を読み取る
• 詳細設計書の読み方 - 詳細設計書全般
• テーブル定義書の読み方 - DBとの対応