2개월 동안 다양한 사람들과 프로젝트를 여러번하니까 내가 부족했던 부분들을 알게 된다.
오늘은 API 설계에서 디테일이 부족했음을 느끼고 관련 내용 정리.
API(Application Programming Interface)는 서비스 간 연결을 가능하게 해주는 핵심 매개체입니다. 특히 RESTful API는 웹 애플리케이션 개발에서 가장 널리 사용되는 아키텍처 스타일로, 설계와 문서화의 품질이 곧 서비스 품질로 직결됩니다.
이번 글에서는 RESTful API를 설계할 때 주의해야 할 핵심 원칙과, 협업을 위한 API 명세서 작성 규칙을 이유와 함께 자세히 정리
.
✅ RESTful API 설계 시 주의사항
1. 자원(Resource)은 명사로 표현하자
REST의 기본 철학은 자원을 URI로 표현하고, 동작은 HTTP 메서드로 구분하는 것입니다. 따라서 URL은 동사가 아니라 자체적으로 의미를 가지는 명사로 작성하는 것이 원칙입니다.
# 좋은 예
GET /users # 사용자 목록 조회
POST /users # 사용자 생성
# 나쁜 예
GET /getUserList # 동작이 URL에 포함되어 있음✔️ 이유
명사 중심의 URI는 API의 목적이 명확하게 드러나며, HTTP 메서드와 조합되어 직관적이고 예측 가능한 인터페이스를 제공합니다.
2. 자원의 계층 구조를 반영하자
리소스 간의 포함 관계나 종속 관계가 있다면, URI를 통해 계층적으로 표현하는 것이 좋습니다.
# 예시
GET /users/1/posts # 1번 사용자의 게시글 목록 조회
GET /users/1/posts/42 # 특정 게시글 조회✔️ 이유
계층적 URI 구조는 리소스 간의 관계를 직관적으로 드러내며, API의 의미 전달력과 구조적 정합성을 높입니다.
3. HTTP 상태 코드를 정확하게 사용하자
API는 요청의 처리 결과를 HTTP 상태 코드로 응답해야 합니다. 이는 클라이언트가 정상/에러 여부를 빠르게 파악하고 처리 로직을 구성할 수 있게 도와줍니다.
| 상태 코드 | 의미 |
|---|---|
| 200 | OK (정상 처리 완료) |
| 201 | Created (생성 성공) |
| 204 | No Content (삭제 성공 등) |
| 400 | Bad Request (요청 오류) |
| 404 | Not Found (자원 없음) |
| 500 | Internal Server Error (서버 에러) |
✔️ 이유
정확한 상태 코드 사용은 클라이언트에게 API의 동작 상태를 표준적인 방법으로 전달하며, 디버깅과 예외 처리에 큰 도움이 됩니다.
4. 응답 포맷은 일관되게, JSON으로
대부분의 RESTful API는 JSON을 기본 포맷으로 사용하며, 아래와 같은 일관된 응답 구조를 유지하는 것이 좋습니다.
{
"status": 200,
"message": "Success",
"data": {
"id": 1,
"name": "Alice"
}
}✔️ 이유
일관된 구조는 프론트엔드 개발자나 외부 API 사용자에게 예측 가능한 경험을 제공하며, 공통 모듈을 통한 응답 처리도 용이하게 만듭니다.
5. API 버전을 명시하자
/api/v1/users
/api/v2/users✔️ 이유
API가 변경되면 기존 클라이언트가 영향을 받을 수 있기 때문에, 안정적인 서비스 운영을 위해 버전 분리는 필수적입니다. URI 버전 관리는 가장 명확하고 일반적인 방법입니다.
📄 API 명세서 작성 시 지켜야 할 규칙
API 설계 못지않게 중요한 것이 바로 명세서 작성입니다. 명세서는 백엔드와 프론트엔드, 외부 파트너 간 인터페이스 계약서이기 때문이죠.
1. 필수 항목을 빠짐없이 작성하자
명세서에는 최소한 다음과 같은 정보가 포함되어야 합니다:
- API 이름 / 설명
- URL
- HTTP Method
- 요청 파라미터 (쿼리, 바디, 헤더 등)
- 응답 구조 (정상 / 에러)
- 응답 예시 (JSON)
- 상태 코드
- 인증/권한 정보
✔️ 이유
명확한 명세는 개발 속도와 커뮤니케이션 효율을 높이며, API 사용 중 발생할 수 있는 불필요한 혼선을 줄여줍니다.
2. 네이밍 규칙은 일관되게
# 예시 (kebab-case 권장)
GET /user-profiles
# 파라미터 예시
?sort=created_at&limit=10✔️ 이유
네이밍 스타일이 통일되어야 코드를 사용하는 입장에서 학습 비용이 줄어들고, 실수 확률이 낮아집니다.
3. 에러 응답은 명세화하고 예측 가능하게
{
"status": 400,
"message": "Invalid email format",
"errorCode": "USER_001"
}✔️ 이유
예외 케이스도 명확히 정의해야 클라이언트가 적절하게 대응할 수 있습니다. 에러코드 체계화는 서비스 운영 중 문제 추적과 로깅에도 효과적입니다.
4. 문서화 도구를 활용하자 (Swagger, Postman)
- Swagger (OpenAPI) : 코드 기반으로 문서 자동화
- Postman : API 테스트 + 문서화
- Redoc, Stoplight, API Blueprint 등도 유용
✔️ 이유
문서 도구를 활용하면 명세서 유지 관리가 쉬워지고, 비개발자와의 소통 및 테스트 효율도 올라갑니다.
5. 요청 / 응답 예시는 꼭 포함하자
POST /users
Content-Type: application/json
{
"email": "alice@example.com",
"password": "secure1234"
}응답 예시:
{
"status": 201,
"message": "User created successfully",
"data": {
"id": 1
}
}✔️ 이유
구체적인 예시는 개발자뿐 아니라 디자이너, QA 등 다양한 실무자가 정확한 기대 동작을 이해하는 데 매우 중요합니다.
