# API Pagination Standard

> API 리스트 엔드포인트의 페이지네이션·필터링·정렬 구현을 분석하고, 통일된 표준 규격을 수립한다.

- Skill: `gaebalai-claude-code-kit-ko/api-pagination-standard` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/api-pagination-standard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/api-pagination-standard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/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. **이행 계획 수립**
   - 기존 엔드포인트별 수정 필요 여부 판단
   - 우선순위 정의
   - 후방 호환 유지 전략 수립
   - 신규 엔드포인트 가이드라인 작성

## 출력 포맷

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

### 현행 분석

#### 발견된 패턴

| 엔드포인트 | 페이지네이션 | 필터 | 정렬 | 통일 여부 |
|------------|--------------|-------|-------|------------|
| [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 오류 반환
- **지원 연산자**:

| 연산자  | 형식                          | 예시                              | 설명    |
| ---- | --------------------------- | ------------------------------- | ----- |
| 등가   | `filter[field]=value`       | `filter[status]=active`         | 완전 일치 |
| 이상   | `filter[field][gte]=value`  | `filter[price][gte]=1000`       | 하한    |
| 이하   | `filter[field][lte]=value`  | `filter[price][lte]=5000`       | 상한    |
| 부분일치 | `filter[field][like]=value` | `filter[name][like]=kim`        | LIKE  |
| 다중값  | `filter[field]=a,b`         | `filter[status]=active,pending` | IN    |


#### 정렬

- **형식**: [예시: `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
```

### 성능 고려 사항

| 항목        | 대응 전략              | 비고                 |
| --------- | ------------------ | ------------------ |
| COUNT 비용  | total_count 기본 미포함 | 요청 시 옵션 제공         |
| 대량 offset | Cursor 방식 기본 적용    | deep pagination 방지 |
| 인덱스 미정렬   | 허용 필드 제한           | 성능 보호              |

### 이행 계획

| 엔드포인트   | 현재 방식             | 변경 사항        | 우선순위 | 호환성 전략         |
| ------- | ----------------- | ------------ | ---- | -------------- |
| /users  | offset 기반         | cursor 방식 도입 | P1   | 기존 파라미터 3개월 유지 |
| /orders | limit/per_page 혼용 | limit 통일     | P2   | deprecated 경고  |

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

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

## 안전 유의사항

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

---

## 종료 조건

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