Posted On 2026년 02월 15일

REST API 설계 원칙과 실전 팁

nobaksan 0 comments
여행하는 개발자 >> 기술 >> REST API 설계 원칙과 실전 팁

REST API는 간단해 보이지만 잘 설계하기는 어렵다. 일관성 있고 직관적인 API를 만들기 위한 원칙과 실전 팁을 정리했다.

리소스 중심으로 설계하자. /getUsers 대신 /users를 쓴다. /createPost 대신 POST /posts를 쓴다. 동사는 HTTP 메서드가 담당한다. URL은 명사로만 구성한다.

HTTP 메서드의 올바른 사용

GET은 조회, POST는 생성, PUT/PATCH는 수정, DELETE는 삭제. 이것이 기본이다. GET은 멱등해야 한다. 같은 요청을 여러 번 보내도 결과가 같아야 한다. POST는 멱등하지 않다.

PUT과 PATCH는 다르다. PUT은 전체 교체, PATCH는 부분 수정이다. 이메일만 바꾸고 싶으면 PATCH를 쓴다. 전체 사용자 정보를 보내야 하면 PUT을 쓴다.

상태 코드

상태 코드를 정확하게 쓰자. 성공하면 200, 생성되면 201, 삭제 성공은 204. 클라이언트 잘못은 4xx, 서버 잘못은 5xx. 404는 찾을 수 없음, 403은 권한 없음, 401은 인증 필요.

200 OK를 남용하지 말자. 에러를 200으로 보내면서 body에 에러 메시지를 넣는 것은 안티패턴이다. 클라이언트가 응답 코드만 보고 성공 여부를 판단하게 하자.

버저닝과 페이지네이션

API 버전 관리가 필요하다. /v1/users, /v2/users 같은 URL 버저닝이 명확하다. 헤더 버저닝도 있지만 덜 직관적이다. 버전 업그레이드 시 호환성을 유지하자.

목록 API는 페이지네이션이 필수다. limit과 offset, 또는 cursor 기반으로 구현한다. 전체 개수와 다음 페이지 정보를 응답에 포함하자. 클라이언트가 페이지를 탐색할 수 있게 한다.

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다

Related Post

문법보다 강한 것: 코드의 미학과 인간의 한계

소프트웨어 개발이라는 행위는 때로 예술과 공학의 경계를 넘나든다. 기계가 이해할 수 있는 언어로 인간의 의도를…

클라우드 시대의 위험한 기본값, 그리고 개발자의 책임

최근 Vercel에서 발생한 보안 사고가 업계에 던진 메시지는 단순하지 않다. 단순히 '또 한 번의 데이터…

데이터의 숨결을 찾아서

미국 노동 시장이 한 줄에 담긴다면, 그것은 마치 거대한 파도 속에서 작은 물방울이 반짝이는 장면일…