REST 계약

HTTP 메서드, NextRequest, 상태 코드, 보안 응답 설계

RESTful API 구현은 CRUD 이름 맞추기가 아니라 메서드 의미, 멱등성, 요청 파싱, 상태 코드, 보안 헤더를 일관된 계약으로 만드는 작업입니다.

01

메서드 의미 확인

GET은 조회, POST는 생성/명령, PUT은 교체, PATCH는 부분 변경으로 의도를 맞춥니다.

semantics
02

요청 데이터 읽기

searchParams, params, headers, body를 분리하고 런타임 스키마로 검증합니다.

NextRequest
03

권한 검사

요청자가 해당 리소스를 읽거나 바꿀 수 있는지 서버에서 확인합니다.

authz
04

도메인 처리

DB와 외부 API 호출을 수행하고 트랜잭션과 재시도 범위를 명확히 둡니다.

work
05

응답 반환

NextResponse.json으로 상태 코드, 본문, 캐시/보안 헤더를 함께 반환합니다.

계약
POST
중복 제출 결제나 주문처럼 중복되면 안 되는 요청은 idempotency key를 고려합니다.
재시도 안전
PATCH
부분 변경 충돌 동시 수정과 오래된 클라이언트 값을 막기 위해 version이나 If-Match가 필요할 수 있습니다.
낙관적 잠금
GET
캐시와 개인화 사용자별 응답은 공유 캐시에 저장되지 않도록 private 정책을 둡니다.
정보 노출 방지

REST API 확인 기준

오류 분리 400, 401, 403, 404, 409, 500을 의미에 맞게 구분합니다.
본문 크기 큰 요청과 파일 업로드는 별도 제한과 스트리밍 전략을 둡니다.
관측 정보 request id와 latency를 로그와 응답 헤더에 연결하면 문제 추적이 쉬워집니다.