REST API 이름의 규칙은 무엇인가요?

REST API 네이밍 규칙: 자원 식별을 위한 명사 복수형 사용 가이드

REST API 네이밍 규칙은 개발자 간의 원활한 협업과 효율적인 인터페이스 관리를 위한 필수적인 지침입니다. 올바른 URI 설계 원칙을 이해하면 코드의 가독성이 향상되고 예기치 못한 오류를 미연에 방지합니다. 표준화된 API 주소 설계 방식과 모범 사례를 학습하여 안정적이고 체계적인 시스템을 구축하는 방법을 확인하십시오.

REST API 네이밍 규칙: 읽기 좋고 유지보수가 쉬운 설계의 기초

REST API 네이밍은 단순히 주소를 만드는 작업을 넘어, 개발자 간의 약속을 정의하는 과정입니다. 핵심 원칙은 URI를 통해 리소스를 식별하고, HTTP 메서드를 통해 행위를 정의하는 것입니다. 소문자 사용, 복수형 명사 지향, 하이픈(-) 활용, 그리고 URI 끝에 슬래시(/)를 붙이지 않는 것 등이 가장 기본이 되는 표준 규칙입니다.

처음 API 설계를 시작할 때 가장 많이 하는 실수가 URI에 get이나 delete 같은 동사를 넣는 것입니다. 저 또한 주니어 시절에 GET /get-user-info 같은 주소를 만들고는 했습니다. 하지만 REST의 철학은 주소창에는 오직 무엇(Resource)인지만 남기는 것입니다. 동작은 HTTP 메서드에 맡겨야 합니다. 이 간단한 원칙 하나가 API의 복잡도를 절반 이하로 줄여줍니다. 정말입니다.

리소스 중심의 URI 설계: 명사와 복수형의 힘

RESTful API의 근간은 리소스입니다. 리소스는 동사가 아닌 명사로 표현해야 하며, 일관성을 위해 복수형(Plural)을 사용하는 것이 업계 표준입니다. 예를 들어 /user 보다는 /users를 사용하는 것이 해당 경로가 컬렉션임을 명확히 나타냅니다.

단수형과 복수형을 혼용하는 것만큼 개발자를 괴롭히는 일도 없습니다. 실무에서 한 프로젝트에 /member/1과 /products가 섞여 있는 것을 본 적이 있는데, 매번 API를 호출할 때마다 문서를 다시 확인해야 했습니다. 시간을 낭비하게 되죠. 복수형 명사를 기본으로 채택하는 것이 일반적인 관행입니다. 이는 컬렉션 내의 특정 항목을 식별할 때 /users/1과 같이 계층 구조를 직관적으로 표현할 수 있기 때문입니다. ^[1]

가독성을 높이는 구분자 사용 규칙

URI는 길어질 수 있으므로 가독성이 중요합니다. 이때 단어 사이의 구분자로 하이픈(-)을 사용해야 합니다. 언더바()는 브라우저의 링크 밑줄 때문에 보이지 않을 위험이 있으며, 전통적으로 RFC 3986 표준에서도 하이픈(-) 사용을 권장합니다. 소문자 사용: URI는 대소문자를 구분하지만, 혼란을 방지하기 위해 반드시 소문자만 사용합니다. 하이픈(-) 활용: 가독성을 위해 단어를 구분할 때 사용합니다. (예: /post-lists) 언더바() 금지: 가독성 및 표준 준수를 위해 사용하지 않습니다. 마지막 슬래시 금지: URI 끝에 /를 포함하지 않습니다. 이는 혼란스러운 리소스 식별을 초래합니다.

행위의 정의: HTTP 메서드와 URI의 관계

URI에 동작을 나타내는 단어를 포함하지 마세요. 대신 HTTP 메서드가 그 역할을 대신합니다. 이는 API를 훨씬 간결하고 예측 가능하게 만듭니다. 실제로 잘 설계된 API는 주소만 봐도 리소스를 알 수 있고, 메서드만 봐도 무엇을 하려는지 알 수 있어야 합니다.

가장 흔한 4가지 메서드의 역할 분담은 다음과 같습니다: 1. GET: 리소스 조회 (데이터를 가져올 때) 2. POST: 리소스 생성 (새로운 데이터를 등록할 때) 3. PUT / PATCH: 리소스 수정 (전체 수정은 PUT, 부분 수정은 PATCH) 4. DELETE: 리소스 삭제. 과거에 보안상의 이유로 모든 요청을 POST로 처리하던 관습이 있었지만, 현재는 각 메서드의 의미를 살리는 것이 더 권장됩니다. 메서드 활용만 잘해도 API 경로의 개수를 효과적으로 줄일 수 있습니다.^[2] 관리 효율성이 비약적으로 상승하는 셈입니다.

계층 구조와 파일 확장자 처리

리소스 간의 연관 관계는 슬래시(/)를 이용한 계층 구조로 표현합니다. /users/1/orders는 1번 사용자의 주문 목록이라는 의미를 직관적으로 전달합니다. 계층이 너무 깊어지면(보통 3단계 이상) API가 복잡해지므로 주의해야 합니다.

또한 URI에 .json이나 .xml 같은 파일 확장자를 포함하지 마세요. 데이터 형식은 HTTP의 Accept 헤더를 통해 협상하는 것이 원칙입니다. 한때는 /api/data.json 형식이 유행하기도 했지만, 이는 리소스 식별자로서의 순수성을 해칩니다. 표준을 따르는 것 - 때로는 이것이 가장 어려운 과제처럼 느껴지기도 하지만, 결국 유지보수 비용을 낮추는 지름길입니다.

버전 관리와 컨트롤러 리소스

API는 시간이 지나면 변합니다. 기존 사용자의 환경을 깨뜨리지 않으면서 새로운 기능을 추가하려면 버전 관리가 필수적입니다. 보통 URI의 시작 부분에 /v1/, /v2/를 명시합니다. 이는 사용자에게 안정성을 보장하는 중요한 신호입니다.

가끔은 리소스로 표현하기 힘든 행위 자체가 중심이 되는 경우가 있습니다. 예를 들어 로그인이나 번역 같은 작업입니다. 이럴 때는 예외적으로 동사를 사용할 수 있으며, 이를 컨트롤러 리소스라고 부릅니다. 하지만 이는 최후의 수단이어야 합니다. 가능하다면 /login 대신 /sessions를 생성(POST)하는 방식으로 리소스화할 수 있는지 먼저 고민해 보는 것이 좋습니다.

REST API 네이밍: 잘못된 예 vs 올바른 예

잘못된 네이밍 (Anti-Pattern)

DELETE /member/delete/1 (불필요하게 경로가 길고 중복됨)

POST /get-users (메서드와 URI 동사가 충돌함)

GET /user_list (언더바 사용 및 명사/동사 혼용)

⭐ 올바른 네이밍 (Best Practice)

DELETE /users/1 (HTTP 메서드로 행위를 정의하여 간결함)

GET /users (단순 명사로 리소스를 명확히 식별)

GET /users (복수형 소문자 사용으로 가독성 확보)

쇼핑몰 스타트업의 API 리팩토링 여정

IT 스타트업 샵메이트의 백엔드 팀은 서비스 런칭 후 6개월 만에 큰 난관에 봉착했습니다. API 주소가 /getProducts, /create_order, /UpdateUser 처럼 제각각이라 프론트엔드 팀과의 소통 비용이 눈에 띄게 증가했기 때문입니다.

처음에는 단순히 주소만 바꾸면 될 줄 알았습니다. 하지만 기존 고객들이 사용 중인 API가 있어 함부로 바꿀 수도 없었습니다. 팀원들은 매번 주소를 외워야 하는 스트레스에 시달렸고, 오타로 인한 버그가 주당 3건 이상 발생했습니다.

결국 팀은 '버전 관리' 도입과 함께 네이밍 표준화를 결정했습니다. 주소에서 동사를 모두 빼고 명사 복수형으로 통일했으며, 동작은 메서드에 맡겼습니다. /v1/orders 처럼 구조를 잡기 시작했습니다.

3개월 후, 새로운 API 도입으로 개발 속도가 40% 향상되었습니다. 오타로 인한 커뮤니케이션 오류는 거의 0에 수렴했고, 신규 개발자 온보딩 시간도 기존 대비 절반으로 줄어드는 쾌거를 이루었습니다.