API 설계 원칙 및 방식 - 100-hours-a-week/2-hertz-wiki GitHub Wiki
1. API 설계 예시 (HTTP Method별 1개씩)
| HTTP | 기능 | URI |
|---|---|---|
GET |
특정 채팅방 메시지 조회 | /api/v1/chat-rooms/{chatRoomId}/new-messages |
POST |
개인정보 등록 | /api/v1/users/information |
PUT |
특정 튜닝 레포트 리액션 토글 | /api/v2/reports/{reportId}/reactions |
PATCH |
개인정보 수정 | /api/v3/users/information |
DELETE |
회원 탈퇴 | /api/v3/users |
2. URI 설계 방식과 원칙
1. 변수 네이밍은 camelCase 사용
API의 요청 데이터와 응답 데이터에서 두 단어 이상으로 이루어진 필드명은 camelCase 형식으로 작성했습니다.
그 이유는 API와 연동되는 Spring Boot의 RequestDTO와 ResponseDTO에서 해당 필드를 바로 사용하기 위해서입니다. 자바에서는 변수명을 camelCase로 작성하는 것이 관례이며, 이를 맞춰줌으로써 불필요한 매핑 로직 없이 일관된 네이밍 구조를 유지할 수 있습니다.
예: oneLineIntroduction, accessToken, userId
2. API URI에서 api와 v1의 이유
api를 URI 앞에 붙임으로써 프론트엔드 라우팅이나 정적 파일 경로(/home,/login등)와의 충돌을 피하고, 백엔드 API 호출 경로를 명확히 구분하기 위함입니다.v1은 버전 관리(versioning) 목적이며, 현재 서비스는 짧은 스프린트 주기로 빠르게 기능을 추가하고 배포하는 운영 전략을 따르기 때문에 향후 v2, v3로의 확장성을 염두에 두고 초기부터 버전을 명시했습니다.
3. URI 마지막 문자로 슬래시(/) 금지
URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 합니다. REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않습니다.
4. URI에서는 밑줄(_) 대신 하이픈(-)
긴 경로나 복합 단어를 포함하는 URI의 경우, 하이픈(-)을 사용하면 가독성이 높아져 URI를 보다 쉽게 읽고 해석할 수 있습니다. 반면, 밑줄(_)은 글꼴에 따라 잘 보이지 않거나 문자가 가려질 수 있어 가독성을 해치는 경우가 많으므로 사용을 지양하는 것이 좋습니다.
5. 리소스 간의 관계를 표현하는 방법
REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현방법으로 사용합니다.
GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)
만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법 → 예를 들어 사용자가 ‘좋아하는’ 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있습니다.
GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)
3. 예외 설계: 그룹 채팅방 입장 API
각 API에서 발생 가능한 모든 예외 상황을 사전에 고려하여 세세하게 예외 처리를 설계했습니다.
그중 한 예로, 특정 그룹 채팅방에 사용자가 입장할 때 발생할 수 있는 다양한 시나리오를 아래와 같이 정의했습니다.
👉 이처럼 클라이언트가 오류를 명확하게 인식하고, 사용자 피드백을 제공할 수 있도록 code + message + data 구조를 일관되게 유지했습니다.