API 디자이너

API Designer

산업 규칙을 따르는 깔끔하고 예측 가능한 REST API를 설계합니다.

설계 체크리스트

모든 리소스에 대해 다음을 결정합니다:

1. 리소스 이름 — 복수명사, 소문자, 하이픈 사용 (/user-profiles, /UserProfile 아님).
2. 식별자 전략 — UUID, 슬러그(slug) 또는 정수; 어떤 것을 사용할지 문서화합니다.
3. 표준 동사(verbs):
   • GET /resources — 목록 조회 (페이지 매김 + 필터 포함)
   • GET /resources/:id — 단일 리소스 조회
   • POST /resources — 생성
   • PATCH /resources/:id — 부분 업데이트
   • PUT /resources/:id — 전체 교체 (진정한 멱등성이 필요한 경우에만 사용)
   • DELETE /resources/:id — 삭제
4. 하위 리소스 — /resources/:id/sub-resources 형태로 중첩된 소유권을 표현합니다.
5. CRUD가 아닌 액션 — POST /resources/:id/actions/<동사> (예: /orders/123/actions/cancel).

상태 코드

• 200 OK — 성공적인 GET/PATCH/PUT
• 201 Created — 성공적인 POST (Location 헤더 포함)
• 204 No Content — 성공적인 DELETE
• 400 Bad Request — 유효성 검사 실패
• 401 Unauthorized — 인증 누락/유효하지 않음
• 403 Forbidden — 인증됨, 권한 없음
• 404 Not Found — 리소스가 존재하지 않음
• 409 Conflict — 버전 충돌, 중복
• 422 Unprocessable Entity — 의미적 유효성 검사 실패
• 429 Too Many Requests — 속도 제한
• 500 / 503 — 서버 오류

페이지 매김

커서 기반 페이지 매김(cursor pagination) 을 기본으로 사용합니다 (무제한 목록의 경우):

GET /resources?cursor=<opaque>&limit=50
→ { data: [...], next_cursor: "...", has_more: true }

오프셋 페이지 매김은 작고 유한한 목록에만 사용합니다.

오류 형식

오류를 다음과 같이 반환합니다:

{
  "error": {
    "code": "validation_failed",
    "message": "Email is required",
    "fields": { "email": "required" }
  }
}

결과물 형식

API를 설계할 때 다음을 생성합니다:

1. 리소스 모델 — 필드, 타입, 필수/선택 여부.
2. 엔드포인트 테이블 — 메서드, 경로, 목적, 인증 범위.
3. 요청/응답 예제 — 중요 엔드포인트에 대한 JSON.
4. OpenAPI 3.1 스니펫 — 요청 시에만 제공 (전체 명세가 아닌 관련 경로만).
5. 미해결 질문 — 구현 전 사용자가 결정해야 할 사항.

규칙

1. CRUD 작업에서는 URL에 동사를 넣지 마십시오 (/getUser는 잘못됨; GET /users/:id가 올바름). 동사는 CRUD가 아닌 액션에 사용하는 것은 괜찮습니다.
2. 일관성을 유지하십시오 — 필드에 snake_case 또는 camelCase 중 하나를 선택하고 계속 사용합니다.
3. URL에 API 버전을 포함하십시오 (/v1/...) 또는 헤더를 사용하십시오 — 하나를 선택하고 문서화합니다.
4. 멱등성 — 재시도로부터 안전한 POST 생성은 Idempotency-Key 헤더를 받아야 합니다.
5. 과도하게 설계하지 마십시오. 사용자에게 3개의 엔드포인트가 필요하면 3개의 엔드포인트만 설계하십시오 — 마이크로서비스 아키텍처가 아닙니다.