좋은 API URL의 원칙: 명사 사용(/users, /orders), 복수형(/users, not /user), 계층 관계 표현(/users/123/orders), 동사 대신 HTTP 메서드(GET/POST/PUT/DELETE).
REST API 설계 모범 사례 2026
실무에서 바로 적용할 수 있는 REST API 설계 원칙과 패턴을 정리한다. URL 네이밍, HTTP 메서드, 상태 코드, 페이지네이션, 버전 관리, 에러 응답 포맷과 OpenAPI 문서화를 포함한다.
한 줄 요약: 좋은 REST API는 리소스 중심 URL, 올바른 HTTP 메서드, 일관된 응답 형식, 버전 관리의 4가지 원칙을 따른다.
REST API는 웹 서비스의 사실상 표준이다. 이 가이드는 실무에서 자주 실수하는 패턴과 모범 사례를 정리한다. 설계 시 한 번 잘못 정하면 하위 호환성 때문에 수정이 어렵기 때문에 처음부터 올바르게 설계해야 한다.
URL 설계 원칙
리소스 중심 URL: /getUsers 대신 /users, /createPost 대신 POST /posts. URL은 명사(리소스)로 구성하고, 동작은 HTTP 메서드(GET/POST/PUT/PATCH/DELETE)로 표현한다. 중첩 리소스는 /users/123/posts처럼 계층적으로 표현한다.
REST API URL 설계 예시# 좋은 설계 GET /api/v1/users # 목록 GET /api/v1/users/123 # 상세 POST /api/v1/users # 생성 PATCH /api/v1/users/123 # 부분 수정 DELETE /api/v1/users/123 # 삭제 GET /api/v1/users/123/posts # 사용자의 포스트 # 나쁜 설계 GET /api/getUser?id=123 POST /api/deleteUser
일관된 응답 형식: 성공과 에러 모두 같은 구조를 사용한다. 에러 응답에는 HTTP 상태 코드와 함께 구체적인 에러 코드와 메시지를 포함한다. 페이지네이션은 ?page=2&limit=20 또는 커서 기반(?cursor=xxx&limit=20)으로 제공한다.
에러 처리 표준화
일관된 에러 응답 형식: HTTP 상태 코드(400, 401, 404, 500 등) + 에러 코드(앱 고유) + 사용자 메시지 + 상세 정보(개발 환경에서만).
페이지네이션과 필터링
대량 데이터 처리: 커서 기반 페이지네이션(offset보다 안정적), 필터(?status=active), 정렬(?sort=-created_at), 필드 선택(?fields=id,name).
API 버전 관리
URL 기반(/api/v1/)이 가장 명확하고 널리 사용된다. 헤더 기반(Accept: application/vnd.api+json;version=1)도 옵션이지만 디버깅이 불편하다. breaking change가 있을 때만 버전을 올리고, 이전 버전은 최소 6~12개월 동안 유지한다.
API 보안 체크리스트
HTTPS 필수, 인증(JWT/API Key), Rate Limiting(사용자당 분당 60회), 입력 검증(Zod/Joi), CORS 설정, SQL Injection 방어(ORM/Prepared Statement), 민감 데이터 필터링(비밀번호 해시를 응답에 포함하지 않기), 로그에 PII 제외.
문서화 팁: OpenAPI(Swagger) 스펙을 먼저 작성하고 코드를 생성하는 'API First' 접근이 가장 효율적이다.
swagger-jsdoc이나 Fastify의 자동 스키마 생성으로 코드와 문서를 동기화하라.apirest설계백엔드패턴