안녕하세요!! 서비스를 만들다 보면 “이 API 뭐 하는 거지?”, “응답 코드가 왜 200인데 에러가 나지?”라는 경험 다들 있으시죠? 그럴 때마다 느끼게 되는 건 바로 — API는 단순히 작동만 하면 되는 게 아니라, 설계가 좋아야 협업과 유지보수도 쉬워진다는 점입니다.
오늘은 개발 실무에서 반드시 알아야 할 RESTful API 설계 원칙을 URI 네이밍, HTTP 메서드, 상태 코드, 버전 관리까지 통합적으로 정리해드릴게요. 이 글 하나면, 다음 프로젝트의 API 설계는 분명히 더 깔끔해질 거예요!
1. RESTful API란 무엇인가?
REST(Representational State Transfer)는 HTTP 기반에서 자원을 표현하고 상태를 전이하는 설계 아키텍처입니다. RESTful API란 이 REST 원칙을 잘 지키며 설계된 API를 의미하죠.
즉, 자원 중심의 URI와 HTTP 메서드를 활용한 행동 표현을 통해 일관성 있고 예측 가능한 API를 만드는 것이 핵심입니다.
2. URI는 자원(Resource)을 명확히 표현해야
- 명사형으로 표현: `/users`, `/posts`, `/products/123`
- 복수형 사용 권장: `/user`보다 `/users`
- 계층적 구조 유지: `/users/123/orders/456` (사용자 123의 주문 456)
❌ 잘못된 예: - `/getUser`, `/updatePost` (행위를 URI에 포함시킴 → RESTful하지 않음) ✅ 올바른 예: - `GET /users/1`, `PUT /posts/10`
3. HTTP 메서드의 역할 분담
- GET: 데이터 조회 (안전함)
- POST: 자원 생성
- PUT: 전체 자원 수정
- PATCH: 일부 자원 수정
- DELETE: 자원 삭제
같은 URI라도 HTTP 메서드에 따라 행동이 달라지기 때문에, 의미 있는 설계가 가능합니다. 예: `GET /articles/3` vs `DELETE /articles/3`
4. 응답 코드도 API의 일부입니다
API 설계 시, HTTP 상태 코드(Status Code)를 제대로 사용하는 것은 클라이언트와의 의사소통 명확성에 매우 중요합니다.
- 200 OK: 정상 응답
- 201 Created: POST 성공 후 생성됨
- 204 No Content: 삭제 성공, 반환 데이터 없음
- 400 Bad Request: 잘못된 요청
- 401 Unauthorized: 인증 실패
- 403 Forbidden: 권한 없음
- 404 Not Found: 자원 없음
- 500 Internal Server Error: 서버 오류
❗ **200으로만 통일하면 디버깅과 오류 추적이 어려워지고, 클라이언트에서도 예외 처리 로직이 무력화됩니다.**
5. 버전 관리는 명시적으로
서비스가 확장되면서 API도 계속 진화합니다. 그렇기 때문에 버전 관리를 통해 과거 API와의 호환성을 유지해야 합니다.
- URI에 버전 명시: `/v1/users`, `/v2/products`
- 헤더 기반 버전 관리: `Accept: application/vnd.company.v1+json`
대부분은 URI 버전이 직관적이고 유지보수에 적합해 실무에서 더 많이 사용됩니다.
6. RESTful 설계 팁 & 반패턴 주의
- 필요 이상으로 URI를 깊게 만들지 말기 (`/users/1/orders/1/items/1` 등)
- 행위는 메서드에, 자원은 URI에 (잘못된 예: `/updateUserInfo`)
- HTTP 응답 메시지에 설명 포함 (`message`, `error`, `code` 등 JSON 구조화)
- 일관된 응답 구조 (성공/실패 모두 동일한 키 구조 유지
결론: 잘 설계된 API는 최고의 개발 문서다
RESTful API는 단순한 코드 인터페이스가 아니라, 팀 전체가 공유하는 ‘사용설명서’입니다. 잘 설계된 API 하나가 프론트엔드, 모바일, QA, PM 모두의 협업 효율을 획기적으로 높일 수 있습니다.
지금부터는 API를 만들 때, 단순히 “돌아가게만”이 아니라 “누가 봐도 이해 가능하게, 변화에도 유연하게” 설계해보세요.
그게 바로 개발자의 실력이고, 팀의 속도라고 생각합니다.
오늘도 글 읽어주셔서 감사합니다~!
내일은 더 좋은 글로 찾아뵐게요ㅎㅎ