REST API란 무엇인가?
REST(Representational State Transfer)는 HTTP를 전송 프로토콜로 사용하는 웹 API 구축을 위한 아키텍처 스타일입니다. RESTful API는 현대 웹 및 모바일 애플리케이션을 지원하는 분리된 프론트엔드와 백엔드 아키텍처를 가능하게 하는 웹 서비스 통신의 지배적인 패턴이 되었습니다.
REST의 핵심 원칙은 상태 비저장성(각 요청에 처리에 필요한 모든 정보 포함), 일관된 인터페이스, 리소스 기반 URL(엔드포인트는 동사가 아닌 명사를 나타냄), 계층화된 시스템입니다.
URL 구조와 리소스 명명
리소스는 복수 명사로 표현해야 합니다: /users, /articles, /orders. 관계는 중첩을 통해 표현됩니다: /users/123/orders는 사용자 123에 속한 주문을 검색합니다. URL에 동사를 사용하지 마세요. HTTP 메서드가 동작을 표현합니다.
일관성이 가장 중요합니다. 다중 단어 리소스 이름에 camelCase 또는 kebab-case 중 하나를 선택해 전체에 적용하세요. 컬렉션 필터, 정렬, 페이지네이션은 쿼리 파라미터를 통해: /articles?status=published&sort=createdAt&page=2&limit=20.
HTTP 메서드와 그 의미
각 HTTP 메서드는 REST가 의존하는 정의된 의미론적 의미를 가집니다: GET은 부작용 없이 리소스를 검색하고(안전하고 멱등), POST는 새 리소스를 생성하고, PUT은 리소스를 완전히 교체하고(멱등), PATCH는 리소스를 부분적으로 업데이트하고, DELETE는 리소스를 제거합니다(멱등).
멱등성은 중요한 속성입니다: 동일한 입력으로 PUT이나 DELETE를 여러 번 호출하면 한 번 호출하는 것과 동일한 결과를 생성해야 합니다. 이는 API를 네트워크 재시도에 탄력적으로 만듭니다.
JSON 응답 구조 설계
JSON 응답 구조의 일관성은 개발자 경험에 가장 큰 영향을 미치는 설계 결정입니다. 성공 응답에는 최상위 data 키를 사용하는 패턴이 널리 채택됩니다: {"data": {"id": 1, "name": "Alice"}}. 컬렉션의 경우: {"data": [...], "meta": {"total": 100, "page": 2, "perPage": 20}}. 오류의 경우: {"error": {"code": "VALIDATION_ERROR", "message": "이메일이 유효하지 않습니다", "field": "email"}}.
타임스탬프는 Unix 타임스탬프보다 사람이 읽기 쉬운 ISO 8601 문자열(2026-03-24T12:00:00Z)로 포함하세요. 모든 리소스에 id 필드를 포함하고, 레코드 수를 노출하거나 추측할 수 있는 자동 증가 정수보다 안정적인 문자열 ID(UUID 또는 슬러그)를 사용하세요.
HTTP 상태 코드
올바른 HTTP 상태 코드는 성공과 실패를 전달하는 API의 주요 메커니즘입니다. 가장 중요한 것들: 200 OK(일반 성공), 201 Created(리소스 생성 성공), 204 No Content(응답 본문 없는 성공, 예: DELETE), 400 Bad Request(클라이언트 오류), 401 Unauthorized(미인증), 403 Forbidden(권한 없음), 404 Not Found(리소스 없음), 422 Unprocessable Entity(유효성 검사 오류), 429 Too Many Requests(요청 제한), 500 Internal Server Error(서버 오류).
오류 객체가 본문에 있는데 200 OK를 반환하는 것은 피하세요. 이는 상태 코드를 검사하는 클라이언트를 망가뜨리는 일반적인 안티패턴입니다.
인증과 권한 부여
REST API의 두 가지 지배적인 인증 패턴은 API 키(서버 간 통신에 적합한 간단하고 상태 비저장 방식)와 OAuth 2.0 / JWT Bearer 토큰(위임된 권한을 가진 사용자 대면 앱에 적합)입니다.
JWT 기반 인증의 경우, 토큰을 Authorization 헤더에 Bearer <token>으로 포함하세요. JWT를 단기간(15분~1시간)으로 유지하고 새 액세스 토큰 획득을 위한 리프레시 토큰을 발급하세요.
API 버전 관리
버전 관리는 Breaking Change가 기존 클라이언트를 방해하는 것을 방지합니다. 주요 접근 방식은 URL 버전 관리(/v1/users)로, 단순성과 캐시 친화성으로 가장 널리 채택됩니다. 이전 주요 버전은 최소 6~12개월의 지원 종료 기간 동안 유지하세요.
지금 사용해보세요 — 무료 온라인 JSON 포맷터
REST API를 빌드하거나 디버깅할 때 JSON 포맷터는 필수입니다. UtiliZest의 JSON 포맷터는 API 응답 페이로드를 즉시 가시화하고 유효성을 검사해 구조 문제, 누락된 필드, 유형 오류를 한눈에 파악할 수 있게 해줍니다.