💻 Claude Code入門 📖 約25分で読めます

Claude CodeでREST APIを設計・実装する

要件定義からテストまでAPI開発の全工程をAIと進める

クロガイド｜Claude＆Claude Codeを無料で学ぼう

AI基礎からプロンプト術、Claude Codeの使い方まで。知識レッスンとクイズ式トレーニングで、AIスキルを段階的にアップ。ユーザー登録不要、すべて無料で今すぐ始められます。

API開発をClaude Codeで加速する

REST APIの開発は、要件定義、エンドポイント設計、データモデル設計、実装、認証、バリデーション、エラーハンドリング、ドキュメント作成、テストと多くの工程を含みます。Claude Codeはこれらすべての工程を対話的にサポートできるため、API開発のスピードと品質を大幅に向上させます。

Claude CodeによるAPI開発の利点

設計段階から支援: RESTfulな設計原則に基づくエンドポイント設計を提案
ボイラープレート削減: ルーティング、ミドルウェア、バリデーション等の定型コードを自動生成
ベストプラクティス適用: セキュリティ、エラーハンドリング、ページネーション等の実装を標準化
テスト自動生成: エンドポイントに対応するテストコードを自動作成

ステップ1: 要件定義をClaude Codeと整理する

API開発の最初のステップは要件を明確にすることです。Claude Codeに要件を伝えて、整理してもらいましょう。

要件定義の会話例

あなた: タスク管理アプリのバックエンドAPIを作りたいです。
機能は以下の通りです。
- ユーザー登録・ログイン（JWT認証）
- プロジェクトのCRUD
- タスクのCRUD（プロジェクトに紐づく）
- タスクにはステータス（未着手/進行中/完了）がある
- タスクの担当者アサイン
Express + TypeScript + Prismaで実装してください。

Claude Code: 要件を整理しました。以下のリソースとエンドポイントを
提案します。

## リソース一覧
| リソース | 説明 |
|---------|------|
| User | ユーザー（認証主体） |
| Project | プロジェクト（タスクのグループ） |
| Task | タスク（作業単位） |

## エンドポイント設計
### 認証 (/api/auth)
- POST /api/auth/register - ユーザー登録
- POST /api/auth/login - ログイン（JWTトークン発行）
- POST /api/auth/refresh - トークンリフレッシュ

### プロジェクト (/api/projects)
- GET    /api/projects - 一覧取得
- POST   /api/projects - 新規作成
- GET    /api/projects/:id - 詳細取得
- PATCH  /api/projects/:id - 更新
- DELETE /api/projects/:id - 削除

### タスク (/api/projects/:projectId/tasks)
- GET    /api/projects/:projectId/tasks - 一覧取得
- POST   /api/projects/:projectId/tasks - 新規作成
- GET    /api/projects/:projectId/tasks/:id - 詳細取得
- PATCH  /api/projects/:projectId/tasks/:id - 更新
- DELETE /api/projects/:projectId/tasks/:id - 削除
- PATCH  /api/projects/:projectId/tasks/:id/assign - 担当者変更

この設計で進めてよろしいですか？

ステップ2: データモデルの設計

エンドポイントが決まったら、データモデルを設計します。Prisma、TypeORM、Sequelizeなどお好みのORMのスキーマを生成してもらいましょう。

Prismaスキーマの生成

あなた: 上記のエンドポイント設計に基づいて、Prismaスキーマを生成してください。
タスクのステータスはenumで定義してください。

Claude Code: Prismaスキーマを生成します。

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

enum TaskStatus {
  TODO
  IN_PROGRESS
  DONE
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String
  password  String
  projects  Project[]
  tasks     Task[]   @relation("assignee")
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Project {
  id          String   @id @default(cuid())
  name        String
  description String?
  owner       User     @relation(fields: [ownerId], references: [id])
  ownerId     String
  tasks       Task[]
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

model Task {
  id          String     @id @default(cuid())
  title       String
  description String?
  status      TaskStatus @default(TODO)
  project     Project    @relation(fields: [projectId], references: [id])
  projectId   String
  assignee    User?      @relation("assignee", fields: [assigneeId], references: [id])
  assigneeId  String?
  dueDate     DateTime?
  createdAt   DateTime   @default(now())
  updatedAt   DateTime   @updatedAt

  @@index([projectId])
  @@index([assigneeId])
  @@index([status])
}

ステップ3: 実装 ― ルーティングとコントローラー

スキーマが決まったら、Express（またはFastAPI等）のルーティングとコントローラーを実装します。

コントローラーの生成依頼

あなた: タスクのCRUDコントローラーを実装してください。
以下の要件を含めてください。
- バリデーション（zodを使用）
- エラーハンドリング
- ページネーション（一覧取得時）

Claude Code: タスクコントローラーを実装します。

// src/controllers/taskController.ts
import { Request, Response, NextFunction } from 'express';
import { z } from 'zod';
import { prisma } from '../lib/prisma';
import { AppError } from '../utils/errors';

const createTaskSchema = z.object({
  title: z.string().min(1).max(200),
  description: z.string().optional(),
  status: z.enum(['TODO', 'IN_PROGRESS', 'DONE']).optional(),
  assigneeId: z.string().optional(),
  dueDate: z.string().datetime().optional(),
});

export const createTask = async (
  req: Request, res: Response, next: NextFunction
) => {
  try {
    const { projectId } = req.params;
    const data = createTaskSchema.parse(req.body);

    // プロジェクトの存在確認
    const project = await prisma.project.findUnique({
      where: { id: projectId }
    });
    if (!project) throw new AppError(404, 'Project not found');

    const task = await prisma.task.create({
      data: { ...data, projectId },
      include: { assignee: { select: { id: true, name: true } } }
    });

    res.status(201).json({ data: task });
  } catch (error) { next(error); }
};

// ... getTasks, getTask, updateTask, deleteTask も同様に実装

ステップ4: 認証とミドルウェア

ミドルウェア	目的	適用範囲
authenticate	JWTトークン検証	認証が必要な全エンドポイント
authorize	リソース所有者チェック	更新・削除系エンドポイント
validate	リクエストボディ検証	POST・PATCHエンドポイント
rateLimit	レートリミット	認証系エンドポイント
errorHandler	統一エラーレスポンス	全エンドポイント（グローバル）

認証実装の依頼プロンプト

あなた: JWT認証ミドルウェアを実装してください。
- アクセストークン（15分）とリフレッシュトークン（7日）
- トークンはAuthorizationヘッダーのBearerスキームで送信
- リフレッシュトークンはhttpOnly cookieに保存
- 不正なトークンには401、期限切れには適切なメッセージを返す

ステップ5: エラーハンドリングの統一

APIのエラーレスポンスは統一されたフォーマットで返すべきです。Claude Codeにエラーハンドリングの実装を依頼しましょう。

統一エラーレスポンスの実装

あなた: エラーレスポンスを統一したいです。以下のフォーマットにしてください。
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "入力内容に誤りがあります",
    "details": [...]
  }
}

Claude Code: グローバルエラーハンドラーを実装します。

// src/middleware/errorHandler.ts
export const errorHandler = (err, req, res, next) => {
  if (err instanceof z.ZodError) {
    return res.status(400).json({
      error: {
        code: 'VALIDATION_ERROR',
        message: '入力内容に誤りがあります',
        details: err.errors.map(e => ({
          field: e.path.join('.'),
          message: e.message
        }))
      }
    });
  }

  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      error: { code: err.code, message: err.message }
    });
  }

  // 予期しないエラー
  console.error('Unexpected error:', err);
  res.status(500).json({
    error: {
      code: 'INTERNAL_ERROR',
      message: 'サーバー内部エラーが発生しました'
    }
  });
};

ステップ6: テストの自動生成

実装が完了したら、テストコードを生成してもらいます。Claude Codeは実装コードを理解した上で、適切なテストケースを提案してくれます。

テスト生成の依頼

あなた: タスクAPIのテストを書いてください。
Jest + supertestを使用し、以下のケースをカバーしてください。
- 正常系: CRUD操作がすべて動作する
- 異常系: バリデーションエラー、認証エラー、存在しないリソース
- エッジケース: 空文字、長い文字列、不正なステータス値

Claude Code: テストを生成します。

// src/__tests__/tasks.test.ts
describe('Tasks API', () => {
  describe('POST /api/projects/:id/tasks', () => {
    it('タスクを正常に作成できる', async () => {
      const res = await request(app)
        .post(`/api/projects/${projectId}/tasks`)
        .set('Authorization', `Bearer ${token}`)
        .send({ title: 'テストタスク', status: 'TODO' });

      expect(res.status).toBe(201);
      expect(res.body.data.title).toBe('テストタスク');
    });

    it('タイトルが空の場合400を返す', async () => {
      const res = await request(app)
        .post(`/api/projects/${projectId}/tasks`)
        .set('Authorization', `Bearer ${token}`)
        .send({ title: '' });

      expect(res.status).toBe(400);
      expect(res.body.error.code).toBe('VALIDATION_ERROR');
    });

    it('認証なしの場合401を返す', async () => {
      const res = await request(app)
        .post(`/api/projects/${projectId}/tasks`)
        .send({ title: 'テスト' });

      expect(res.status).toBe(401);
    });
  });
  // ... 他のテストケースも同様
});