REST 순수성보다 명확한 API를 설계하라

출처 및 AI 안내: 이 글은 제미니의 개발실무 유튜브를 기반으로 작성되었습니다. gpt-5.6-sol 모델을 사용해 생성·편집했습니다.

REST는 리소스 중심 HTTP API를 만드는 데 유용한 생각을 제공한다. 하지만 계약을 쓰고 관리할 사람보다 앞서는 순수성 시험으로 쓰면 도움이 줄어든다.

나는 엔드포인트가 완전히 RESTful한지부터 묻지 않는다. 클라이언트가 분명하게 사용할 수 있는지, 팀이 일관되게 적용할 수 있는지, 비즈니스 행위를 어색한 모양으로 밀어 넣지 않고 표현하는지를 먼저 본다.

규칙을 빌리되 숭배하지 않는다

리소스 이름, HTTP 메서드, 상태 코드는 팀에 공통 언어를 준다. 도움이 되는 곳에서는 적극 활용하면 된다. 그렇다고 경로에 동사가 있다는 이유만으로 잘못됐다고 하거나, 주변 계약과 관계없이 생성 성공을 언제나 한 가지 방식으로만 표현해야 한다고 생각하지는 않는다.

예를 들어 주문 취소 엔드포인트는 명시적인 cancel 행위를 넣는 편이 사용하는 사람에게 더 쉬울 수 있다. 팀이 그 형태를 일관되게 쓰고 행위가 분명하다면 동사가 있다는 사실이 가장 먼저 고칠 문제는 아니다.

상태 코드도 같다. 나는 성공 응답을 단순하게 두고 클라이언트 오류는 의미 있는 차이가 있을 때 더 다양하게 쓰는 편이다. 다른 팀은 더 세밀한 REST 규칙을 선택할 수 있다. 중요한 것은 서버와 클라이언트가 합의하고 동작을 예측할 수 있는가이다.

API는 구체적인 당사자 사이의 계약이다

클라이언트용 API라면 클라이언트 개발자와 이야기해야 한다. 어떤 규칙이 중요한 성질을 지키지도 않으면서 연동만 어렵게 한다면 조정할 수 있다. 팀이나 회사에는 이미 HTTP 규칙이 있는 경우가 많다. 모든 REST 해석을 만족하지 않더라도 제품 전체의 일관성이 한 엔드포인트의 순수성보다 가치 있을 수 있다.

API 자체가 제품인 플랫폼은 조건이 다르다. 변경 영향이 넓으므로 문서화된 공개 규칙과 버전, 일관성이 훨씬 중요하다. 한 클라이언트 팀이 쓰는 내부 엔드포인트와 같은 기준으로 볼 수 없다.

엔드포인트 분리는 의미 있는 기능을 따라야 한다. 사용자와 주문 작업을 액션 파라미터 하나로 통과시키는 범용 엔드포인트보다 서로 다른 경로로 표현하는 편이 읽기 쉽고 우발적 결합도 줄인다. 다만 실제 유스케이스를 보지 않고 추상 규칙만으로 정확한 경로를 정할 수는 없다.

API를 비즈니스 중심과 분리한다

API는 클라이언트에 내놓는 스펙이다. API 자체가 제품인 경우를 제외하면 핵심 비즈니스 모델과 같지 않다. 중요한 비즈니스 개념과 행위는 HTTP 경로와 응답 모양에서 분리할 수 있어야 한다.

관심사를 세 가지로 나눠 볼 수 있다.

1. 클라이언트에 공개하는 API 계약
2. 중요한 규칙을 가진 비즈니스 행위
3. 둘을 연결하고 실제 작업을 수행하는 구현

경계가 분명하면 클라이언트 편의를 위해 API를 바꿔도 도메인을 다시 쓰지 않아도 된다. 복수형 명사나 상태 코드 논쟁이 더 어려운 비즈니스 행위 설계를 대신하는 것도 막을 수 있다.

REST는 좋은 참고 자료다. 많은 HTTP 시스템을 이해하기 쉽게 만든 패턴을 담고 있다. 이유를 가지고 적용하고 결과의 통일성을 지키자. 실제 클라이언트와 운영 맥락에서 더 단순한 계약이 낫다면 그 선택도 열어 두면 된다.