API Pagination Standard

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

API의 리스트형 엔드포인트에서 사용되는 페이지네이션, 필터링, 정렬 방식을 분석하고 통일된 표준을 수립한다.
현행 구현의 불일치 지점을 식별하고, 클라이언트가 일관된 방식으로 데이터를 조회할 수 있도록 표준 스펙을 정의한다.
대용량 데이터 처리 효율성, 성능, 사용성의 균형을 고려한다.

입력

• API 코드베이스 디렉토리 또는 리스트 엔드포인트 파일 (필수)
• 기존 페이지네이션 규약 (선택)
• 예상 데이터 규모 (선택)
• 선호 방식 (offset / cursor / keyset) (선택)
• 정보가 부족하면 사용자에게 질의할 것

절차

1. 현행 구현 분석

   • Grep으로 page, limit, offset, cursor, per_page, skip, take 등 검색
   • 필터 구현 방식 분석 (query param / body / DSL)
   • 정렬 파라미터 (sort, order, order_by) 탐색
   • 응답 메타데이터 구조 수집
   • 엔드포인트 간 불일치 목록화

2. 페이지네이션 방식 결정

   • Offset / Cursor / Keyset 비교
   • 데이터 규모 및 실시간성 고려
   • 기본 페이지 크기 및 최대 제한 정의

3. 필터링 규격 설계

   • 파라미터 네이밍 규칙 정의
   • 지원 연산자 정의
   • 화이트리스트 기반 필드 제한
   • 잘못된 파라미터 처리 정책 정의

4. 정렬 규격 설계

   • 단일 및 복수 필드 정렬 문법 정의
   • 허용 필드 제한
   • 기본 정렬 정의
   • 인덱스 전략 고려

5. 응답 구조 표준화

   • meta 구조 통일
   • 방식별 응답 샘플 정의
   • total_count 반환 정책 정의
   • 빈 결과 처리 방식 정의

6. 이행 계획 수립

   • 기존 엔드포인트별 수정 필요 여부 판단
   • 우선순위 정의
   • 후방 호환 유지 전략 수립
   • 신규 엔드포인트 가이드라인 작성

출력 포맷

## 페이지네이션·필터·정렬 표준 규격서

### 현행 분석

#### 발견된 패턴

| 엔드포인트 | 페이지네이션 | 필터 | 정렬 | 통일 여부 |
|------------|--------------|-------|-------|------------|
| [PATH] | [limit/offset] | [query 기반] | [sort=] | 불일치 |

#### 불일치 항목

| 항목 | 패턴 A | 패턴 B | 대상 엔드포인트 |
|------|--------|--------|----------------|
| 페이지 크기 | limit | per_page | [/users, /orders] |

### 표준 규격

#### 페이지네이션

- **채택 방식**: Cursor 기반 (대규모 데이터 대응)
- **선정 이유**: 대용량 데이터에서 안정적이며 offset 성능 저하 방지
- **기본 페이지 크기**: 20
- **최대 페이지 크기**: 100

**요청 예시**

GET /api/v1/resources?page=2&per_page=20

**응답 구조**:
```json
{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total_count": 150,
    "total_pages": 8
  },
  "links": {
    "first": "/api/v1/resources?page=1&per_page=20",
    "prev": "/api/v1/resources?page=1&per_page=20",
    "next": "/api/v1/resources?page=3&per_page=20",
    "last": "/api/v1/resources?page=8&per_page=20"
  }
}

필터링

• 파라미터 형식: [예시: filter[field]=value]
• 화이트리스트 기반 필드 제한
• 잘못된 필터 파라미터: 400 오류 반환
• 지원 연산자:

정렬

• 형식: [예시: sort=field / sort=-field(내림차순)]
• 복수 필드: [예시: sort=status,-created_at]
• 기본 정렬: [예시: -created_at(새로운 순서)]
• 정렬 가능 필드 제한: 인덱스 필드만 허용

요청 예시:

GET /api/v1/resources?sort=-created_at,name&filter[status]=active&page=1&per_page=20

성능 고려 사항

이행 계획

신규 엔드포인트 가이드라인

1. 리스트 API는 반드시 본 표준 준수
2. 필터 가능 필드는 문서에 명시
3. 기본 정렬 필수 정의
4. 최대 페이지 크기 초과 시 400 반환
5. total_count는 옵션 요청 시만 계산

## 안전 유의사항

- 문서 작성만 수행하고 구현 변경은 하지 않는다.
- SQL 인젝션 위험 패턴 발견 시 반드시 경고한다.
- 필터 대상에 민감 정보가 포함되지 않도록 주의한다.
- 대규모 데이터 전량 반환 가능 구조는 반드시 지적한다.
- total_count 계산이 성능에 미치는 영향 명시한다.

---

## 종료 조건

위 형식에 따른 표준 규격서를 출력하면 종료한다.  
페이지네이션·필터링·정렬 규칙이 명확히 정의되어 있고, 현행 구현과의 차이 및 이행 계획이 포함되어야 한다.  
실제 코드 수정은 사용자 지시를 기다린다.