Route Handler Readiness

배열 예제 API를 실제 서비스 API로 올릴 때 고정할 계약

app/api/users/route.ts가 동작하는 것에서 멈추지 않고, 입력 검증, 저장소, 인증, 응답 코드, 배포 런타임까지 하나의 API 계약으로 정리합니다.

1

경로 계약

파일 구조가 URL이므로 컬렉션과 단일 리소스 경로를 나눕니다.

/api/users/[id]
2

입력 검증

searchParams, params, request.json()의 필수값과 타입을 확인합니다.

400 Bad Request
3

저장소 연결

메모리 배열 대신 Prisma나 DB 쿼리로 영속 데이터를 읽습니다.

db.user.findMany()
4

보호 경계

세션과 역할이 필요한 API는 핸들러 초반에 차단합니다.

401 / 403
5

배포 조건

환경 변수, 서버리스 시간 제한, CORS, 스트리밍 응답을 점검합니다.

runtime config

핸들러 안의 기본 순서

1. 요청 입력 읽기

2. 세션과 필수값 검증

3. DB 조회 또는 변경

4. 상태 코드와 JSON 모양 고정

NextResponse.json(result, { status })
상황
상태
본문
클라이언트 처리
목록 조회
200
users 배열
검색 결과 렌더링
생성 성공
201
newUser
상세 화면 또는 목록 갱신
검증 실패
400
message
폼 오류 표시
리소스 없음
404
message
빈 상태 또는 이동 처리