REST APIで複数ID指定を実装する：NestJS + Zodによる実践メモ

1. 概要 { #overview }

REST APIで複数のリソースをIDで取得する機能の実装パターンと、NestJS + Zodを使った実装方法を解説します。

1.1 解決したい課題 { #problem }

単一のAPIリクエストで複数のユーザー情報を取得したい場合の最適な実装方法を検討します。

1.2 実装要件 { #requirements }

• 最大件数のIDを一度に指定可能
• 既存APIとの互換性維持
• 開発者に優しいインターフェース
• 型安全性の確保

2. 実装パターンの比較 { #patterns }

2.1 主要な3パターン { #three-patterns }

カンマ区切りパターン（推奨）

GET /api/users?ids=1,2,3,4,5

• 採用企業: Twitter、Google、Amazon
• メリット: URL最短、実装シンプル
• デメリット: カンマエスケープが必要な場合あり

配列形式パターン

GET /api/users?ids[]=1&ids[]=2&ids[]=3

• 採用企業: PHP/Rails系フレームワーク
• メリット: 配列であることが明確
• デメリット: URL長い、エンコーディング問題

リピートパラメータパターン

GET /api/users?id=1&id=2&id=3

• 採用企業: 一部のJavaフレームワーク
• メリット: HTTP標準準拠
• デメリット: 最も長いURL、実装により挙動が異なる

3. NestJS + Zodでの実装 { #implementation }

3.1 Zodスキーマ定義 { #zod-schema }

// schemas/user-query.schema.ts
import { z } from 'zod';

export const listUsersQuerySchema = z.object({
  ids: z
    .string()
    .regex(/^\d+(,\d+)*$/, 'IDはカンマ区切りの数値である必要があります')
    .transform(value => value.split(',').map(Number))
    .pipe(
      z.array(z.number().int().positive())
        .min(1, '最低1つのIDが必要です')
        .max(100, '最大100つまでのIDを指定できます')
    )
    .optional(),
});

3.2 コントローラー実装 { #controller }

@Controller('users')
export class UsersController {
  @Get()
  async list(@Query() query: ListUsersDto): Promise<UserResponse[]> {
    return this.usersService.list(query.ids);
  }
}

3.3 サービス層での注意点 { #service-tips }

async list(ids?: number[]): Promise<UserResponse[]> {
  const users = await this.prisma.user.findMany({
    where: { id: { in: ids } },
  });

  // 重要: リクエストされたID順序を保持
  const userMap = new Map(users.map(u => [u.id, u]));
  return ids
    .map(id => userMap.get(id))
    .filter(Boolean);
}

4. ケーススタディ：実装前後の比較 { #case-study }

4.1 実装前の問題点 { #before }

既存の実装: 単一IDのみ対応

// N+1問題が発生
const users = await Promise.all(
  userIds.map(id => fetch(`/api/users/${id}`))
);

発生していた問題:

• 10ユーザー取得に10回のAPIコール
• レスポンス時間: 平均800ms
• ネットワーク負荷: 高

4.2 実装後の改善 { #after }

新しい実装: 複数ID対応

// 1回のAPIコールで完結
const users = await fetch(`/api/users?ids=${userIds.join(',')}`);

想定改善結果:

• APIコール数: 10回 → 1回
• レスポンス時間: 800ms → 150ms
• コード行数: 5行 → 1行

5. エラーハンドリング { #error-handling }

5.1 バリデーションエラーの例 { #validation-errors }

// 無効なフォーマット
GET /api/users?ids=1,invalid,3

{
  "statusCode": 400,
  "message": "バリデーションエラー",
  "errors": [{
    "field": "ids",
    "message": "IDはカンマ区切りの数値である必要があります"
  }]
}

5.2 URL長制限への対応 { #url-limit }

// 100件超える場合はPOSTエンドポイントを提供
@Post('batch')
async findUsersBatch(@Body() body: { ids: number[] }) {
  return this.usersService.list(body.ids);
}

6. フロントエンド実装例 { #frontend }

6.1 React Hookでの利用 { #react-hook }

function useUsers(ids: number[]) {
  const [users, setUsers] = useState<User[]>([]);
  
  useEffect(() => {
    if (ids.length === 0) return;
    
    fetch(`/api/users?ids=${ids.join(',')}`)
      .then(res => res.json())
      .then(setUsers);
  }, [ids.join(',')]);

  return users;
}

7. 運用のベストプラクティス { #best-practices }

7.1 実装チェックリスト { #checklist }

• カンマ区切り形式の採用
• 最大件数制限
• ID順序の保持
• 明確なエラーメッセージ
• 大量データ用のPOSTエンドポイント

7.2 パフォーマンス最適化 { #performance }

// データベースインデックスの活用
CREATE INDEX idx_users_id ON users(id);

// バッチ処理での取得
const BATCH_SIZE = 50;
const batches = chunk(ids, BATCH_SIZE);

8. まとめ { #conclusion }

8.1 導入効果 { #results }

• 開発効率: N+1問題の解消により実装がシンプルに
• パフォーマンス: レスポンス時間大部改善
• 保守性: Zodによる型安全性でバグ削減
• 互換性: 業界標準パターンで他サービスとの連携容易

8.2 今後の拡張案 { #future }

• GraphQL移行の検討（より柔軟なクエリが必要な場合）
• キャッシュ戦略の実装（頻繁にアクセスされるIDセット）
• フィールド選択機能の追加（fields=id,name,email）

カンマ区切りパターンとZodの組み合わせにより、シンプルで堅牢なAPIを実現できました。特に複数リソースの一括取得は、現代のWebアプリケーションにおいて必須の機能です。