[개발 일기] 2025.05.24 - REST API의 URL에 대한 개인적인 생각

💡 개요

 

오늘 API 명세서를 작성하다가 여러 가지 고민거리가 생겼다. 오늘은 그 고민에 대해 정리해 보자.

 

 

🛠️ 복수 or 단수

 

난 최근까지 REST의 URL을 나타낼 때

• /api/v1/member
• /api/v1/board

 

이런 식으로 단수형으로 표현했다.

 

 

하지만 이는 REST의 URL 규칙에 어긋난다고 한다.

 

 

REST에서는 일반적으로 "리소스는 복수형"으로 표현하는 것이 권장된다.

• /api/v1/members
• /api/v1/boards

 

이유는 리소스의 집합(복수)을 다루는 것이라는 REST의 철학 때문이다.

 

 

만약 회원 데이터 중에서 한 회원의 정보를 조회할 경우 /members/{id} 와 같이 개별 리소스를 표현할 수 있고, /members 을 통해 회원 리스트를 자연스럽게 조회할 수 있다.

 

 

 

🛠️ URL에는 오로지 리소스만..?

 

REST API의 특징은 리소스는 URL으로 표현하고, 그에 해당하는 행위는 HTTP Method을 사용해 나타내는 것이다.

• POST /members → 멤버 생성
• GET /members/{id} → 특정 멤버 조회
• PUT /members/{id} → 특정 멤버 수정
• DELETE /members/{id} → 특정 멤버 삭제

 

이렇게 URL 자체는 명사 중심으로, 행동(동사)은 HTTP Method로 표현하는 것이 REST의 핵심이다.

 

 

하지만 현실에선 이 원칙을 완벽하게 지키는 것은 매우 어렵다.

 

 

왜냐하면 특정 비즈니스의 행동이 너무 다양하기 때문에 HTTP Method으로 완벽하게 모든 작업을 표현할 수 없기 때문이다.

 

 

그렇기 때문에 어쩔 수 없이 URL에 행위를 나타내는 문자열을 사용하곤 한다.

 

 

대표적인 예시가 바로 현재 내가 진행 중인 프로젝트의 ‘화장실 공유’ 기능이다.

 

 

이 기능은 서비스에서 제공하는 화장실 정보를 카카오톡이나 문자 등으로 사용자에게 공유할 때 사용된다.

 

 

하지만 이처럼 공유(share)와 같은 명확한 도메인 행위를 완벽하게 표현할 수 있는 HTTP Method는 사실상 존재하지 않는다. (물론, 내가 잘 모르는 특수한 방법이 있을 수도 있다.)

 

 

그래서 결국 아래와 같은 형태로 API를 정의했다:

 

POST /api/v1/restrooms/{restroomId}/share

 

REST 관점에서 보면 share라는 행위(동사)가 URL에 포함되기 때문에 엄밀히 말해 RESTful하지 않다고 볼 수 있다.

 

 

하지만 URL만 봐도 "아, 화장실 정보를 공유하는 기능이구나!" 하고 명확하게 이해할 수 있다.

 

 

REST의 원칙도 중요하지만, 명확한 의도 전달과 실제 사용성 측면에서의 실용성이 더 우선이라는 점을 보여주는 좋은 사례라고 생각한다.