api-endpoint-scaffolder

API エンドポイントのスキャフォールディング

手順

新しい API エンドポイントを作成するときは、次の手順に従います。

1. フレームワークを特定します（Express、Next.js、FastAPI など）
2. HTTP メソッドを決定します（GET、POST、PUT、PATCH、DELETE）
3. リクエストとレスポンスの型を定義します
4. ベストプラクティスに従って実装します

テンプレート

Next.js App Router（TypeScript）

// app/api/[resource]/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const RequestSchema = z.object({
  // Define your schema
});

export async function GET(request: NextRequest) {
  try {
    const { searchParams } = new URL(request.url);
    // Implementation
    return NextResponse.json({ data }, { status: 200 });
  } catch (error) {
    console.error('[API] Error:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();
    const validated = RequestSchema.parse(body);
    // Implementation
    return NextResponse.json({ data }, { status: 201 });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

Express（TypeScript）

import { Router, Request, Response, NextFunction } from 'express';
import { z } from 'zod';

const router = Router();

const CreateSchema = z.object({
  // Define schema
});

router.post('/', async (req: Request, res: Response, next: NextFunction) => {
  try {
    const data = CreateSchema.parse(req.body);
    // Implementation
    res.status(201).json({ success: true, data });
  } catch (error) {
    next(error);
  }
});

export default router;

ベストプラクティス

1. Zod、Yup などを使用して、必ず入力を検証します
2. 適切な HTTP ステータスコードを使用します：
   • 200：成功
   • 201：作成済み
   • 400：不正なリクエスト
   • 401：認証されていません
   • 403：アクセス禁止
   • 404：見つかりません
   • 500：サーバーエラー
3. エラーをログに記録しますが、内部情報をクライアントに公開しないでください
4. 一貫したレスポンス形式を使用します
5. 公開エンドポイントにはレート制限を追加します
6. 可能な場合は、OpenAPI/Swagger でドキュメントを作成します