RESTful API는 현대 웹 개발의 중심에 있는 아키텍처 스타일입니다. 그러나 “RESTful하다”는 표면적인 외형만 따르고, 실제로는 REST의 원칙에서 벗어난 API들이 현업에서 너무 자주 발견됩니다. 이 글에서는 RESTful API 설계에서 개발자들이 흔히 저지르는 실수들을 실제 사례를 바탕으로 짚어보고, 그에 대한 개선 방안과 Best Practice를 깊이 있게 다루겠습니다.
📌 목차
- 1. RESTful이라는 환상
- 2. RESTful API란 무엇인가?
- 3. RESTful API 설계 시 흔히 저지르는 실수 8가지
- 4. 실제 사례 분석: 잘못된 API 설계 vs 개선된 API 설계
- 5. RESTful API 설계를 위한 Best Practices
- 6. 결론: API는 하나의 계약(Contract)이다
1. RESTful이라는 환상
“우리 API는 RESTful하게 설계됐습니다.” 많은 개발자들이 자신 있게 말하곤 합니다. 하지만 실제로 API 엔드포인트를 열어 보면, 동사로 가득한 URI, GET 요청으로 수행되는 데이터 변경, 모든 응답에 200 OK만 사용하는 구조 등 REST의 철학에서 한참 벗어난 사례들을 흔히 마주칩니다.
REST는 단순한 기술 규격이 아니라, 자원을 중심으로 설계된 철학적 접근 방식입니다. 하지만 실무에서는 이 철학이 생략되고, 단지 “REST API를 만든다”는 형식적인 목표만 남게 되는 경우가 많습니다. 특히 스타트업이나 빠른 MVP 제작 과정에서는 기능 구현에 집중한 나머지 설계 원칙이 무시되기도 하죠.
이 글에서는 단순히 REST의 정의를 설명하는 데 그치지 않고, 실제 API 설계에서 자주 발생하는 실수들을 사례 중심으로 분석합니다. 그리고 각각의 문제에 대해 어떻게 개선할 수 있는지, 어떤 방식이 진정한 RESTful 접근인지를 함께 고민해 보겠습니다.
RESTful API는 단지 서버와 클라이언트 간 통신을 위한 통로가 아닙니다. 그것은 서비스의 사용성을 결정짓는 인터페이스이며, 개발자 경험(Developer Experience)의 핵심입니다. 명확하고 일관된 API는 유지보수가 쉬울 뿐 아니라, 프론트엔드와 백엔드 간의 커뮤니케이션 비용을 획기적으로 줄여줍니다.
지금부터 RESTful API 설계에서 흔히 마주치는 실수들을 하나씩 짚어보고, 그것이 왜 문제인지, 어떻게 개선할 수 있는지 구체적인 예시를 통해 알아보겠습니다.
2. RESTful API란 무엇인가?
REST(Representational State Transfer)는 2000년, 로이 필딩(Roy Fielding)의 박사학위 논문에서 처음 제시된 아키텍처 스타일입니다. 웹의 기본 원칙에 기반하여, 자원을 식별하고 조작하는 방식으로 설계되어 있어 확장성과 호환성이 뛰어난 특징을 가집니다.
RESTful API는 이 REST의 철학을 따르는 API를 의미합니다. 다만 많은 개발자들이 “HTTP를 사용하면 RESTful”하다고 오해하기 쉽습니다. 단순히 URL과 HTTP 메서드를 사용하는 것이 아니라, 다음과 같은 핵심 원칙들을 만족해야 비로소 ‘RESTful’하다고 할 수 있습니다.
✅ RESTful API의 핵심 구성 요소
- 자원(Resource): URI로 식별되는 엔터티. 예:
/users,/products - 표현(Representation): 자원의 상태를 표현하는 데이터 포맷. 일반적으로 JSON 사용
- 메서드(Method): HTTP 동사를 통해 자원에 대한 행위를 표현. 예: GET, POST, PUT, DELETE
- 상태코드(Status Code): 요청에 대한 결과를 표현하는 HTTP 응답 코드
🔍 RESTful하지 않은 API란?
RESTful하지 않은 API는 대부분 자원의 개념이 흐릿하거나, HTTP 메서드를 단지 호출 수단으로만 사용하며, 응답 또한 HTTP 프로토콜의 의미를 무시하고 일관되지 않은 메시지를 반환합니다.
예를 들어, 다음과 같은 API는 RESTful하지 않습니다:
GET /getUserById?id=123
위 API는 동사(getUserById)를 URI에 사용하고 있으며, 자원을 식별하는 데 HTTP 메서드와 URI 구조를 제대로 활용하지 못한 사례입니다. 이보다는 다음처럼 리소스 중심으로 설계하는 것이 RESTful한 방식입니다:
GET /users/123
RESTful한 설계는 API가 직관적이고 예측 가능하게 만들어줍니다. 클라이언트는 서버가 어떻게 동작할지 미리 예측할 수 있고, API 문서가 없이도 기본적인 사용법을 유추할 수 있는 수준이 됩니다.
이제 RESTful API의 기본기를 정리했으니, 다음 단락에서는 실무에서 자주 마주치는 설계 실수들을 구체적인 사례와 함께 살펴보겠습니다.
3. RESTful API 설계 시 흔히 저지르는 실수 8가지
3.1 리소스가 아닌 동작 중심 URI
RESTful 설계 원칙에서 가장 먼저 지적되는 오류 중 하나는 바로 **동사형 URI**입니다. 이는 RPC 스타일에 가까운 API 설계 방식으로, 서버의 기능(function)을 URI로 표현하고, 클라이언트가 이를 호출하는 형태를 띱니다. 하지만 REST는 **자원 중심(Resource-Oriented)**으로 접근해야 하며, 리소스의 상태를 표현하는 방식으로 URI를 설계해야 합니다.
🚫 잘못된 예시: 동사 중심 URI
GET /getUser
POST /createOrder
PUT /updateProfile
DELETE /deleteComment
이러한 URI는 마치 함수를 호출하듯 서버에 명령을 전달하는 방식으로 설계되었습니다. 하지만 이는 REST의 철학과 맞지 않으며, API가 무슨 일을 하는지는 알 수 있어도 **무슨 자원을 다루고 있는지** 명확하지 않습니다.
✅ 개선된 예시: 자원 중심 URI
GET /users/123
POST /orders
PUT /users/123/profile
DELETE /comments/456
개선된 예시에서는 URI가 명확하게 **리소스(자원)**를 표현하고 있으며, 어떤 자원에 어떤 작업을 수행하는지를 HTTP 메서드로 구분하고 있습니다. 예를 들어:
GET /users/123는 ID가 123인 사용자의 정보를 조회합니다.POST /orders는 새로운 주문을 생성합니다.PUT /users/123/profile은 특정 사용자의 프로필을 갱신합니다.DELETE /comments/456는 ID가 456인 댓글을 삭제합니다.
📌 핵심 포인트
| 항목 | 비RESTful | RESTful |
|---|---|---|
| URI | /getUser | /users/123 |
| 의미 | 동작(함수 호출) | 자원 조회 |
| 유연성 | 낮음 (기능 중심) | 높음 (자원 중심) |
RESTful한 API를 설계하려면 ‘무엇을 한다’ 보다는 ‘무엇에 대해 한다’는 관점의 전환이 필요합니다. URI는 기능을 설명하는 것이 아니라 **데이터의 구조와 자원의 위치를 표현하는 것**임을 항상 기억해야 합니다.
3.2 HTTP 메서드의 오용
RESTful API에서 HTTP 메서드는 단순한 호출 수단이 아닙니다. 각 메서드는 고유한 의미와 용도를 지니며, 이를 정확히 준수하는 것이 REST의 핵심입니다. 하지만 실무에서는 이 메서드들이 잘못된 의미로 사용되는 사례가 자주 발견됩니다.
🚫 잘못된 사용 사례
다음은 HTTP 메서드를 잘못 사용한 예입니다:
GET /deleteUser?id=123
POST /getUserInfo
DELETE /logout
위 API들은 RESTful하지 않은 전형적인 예입니다. GET은 서버에 영향을 주지 않는 **안전한(safe)** 요청이어야 하며, POST는 리소스를 생성하거나 서버 상태를 변경할 때 사용해야 합니다. DELETE는 자원을 삭제할 때만 사용해야 하며, 로그아웃처럼 서버의 인증 상태를 단절하는 행위에는 적절하지 않습니다.
✅ 올바른 사용 예시
HTTP 메서드는 다음과 같은 의미를 가져야 합니다:
GET /users/123 // 사용자 정보 조회 (조회 전용)
POST /users // 새로운 사용자 생성
PUT /users/123 // 기존 사용자 정보 전체 갱신
PATCH /users/123 // 기존 사용자 정보 일부 갱신
DELETE /users/123 // 사용자 삭제
📌 메서드 선택 시 고려할 점
| 메서드 | 역할 | 특징 |
|---|---|---|
| GET | 데이터 조회 | 안전(Safe), 멱등성 있음(Idempotent) |
| POST | 데이터 생성 | 비멱등성, 상태 변화 발생 |
| PUT | 전체 갱신 | 멱등성 있음 |
| PATCH | 부분 갱신 | 멱등성 보장되지 않음 |
| DELETE | 데이터 삭제 | 멱등성 있음 |
정확한 메서드 사용은 단순한 규칙이 아니라, API의 예측 가능성과 신뢰성을 높이는 중요한 설계 기준입니다. 잘못된 메서드 사용은 보안 문제나 클라이언트 오작동을 야기할 수 있으며, API 사용성을 크게 저해할 수 있습니다.
결국, RESTful API의 본질은 **HTTP의 철학을 존중하면서 자원을 표현하는 것**입니다. 메서드 하나하나가 그 철학을 구성하는 기둥이므로, 그 의미를 명확히 이해하고 설계에 적용해야 합니다.
3.3 일관성 없는 URI 구조
API의 URI는 곧 그 API의 ‘주소 체계’입니다. 주소가 들쭉날쭉하면 사용자는 길을 잃기 쉽습니다. 마찬가지로, 일관되지 않은 URI 패턴은 API 사용성을 떨어뜨리고, 문서화를 어렵게 하며, 클라이언트와의 계약(Contract)을 불안정하게 만듭니다.
실무에서는 종종 다음과 같은 문제들을 마주칩니다:
- 동일한 목적의 URI가 서로 다른 명명 규칙을 사용하는 경우
- 복수형/단수형 혼용 (
/uservs/users) - 계층 구조가 무시되거나 과하게 중첩된 경우
- 파일 경로처럼 설계된 URI (
/user/edit.php)
🚫 잘못된 예시
GET /user-list
GET /users/info
POST /create_user
PUT /userUpdate
DELETE /delete-user
이러한 구조는 개발자마다 설계 철학이 다르거나, API가 팀 간에 나누어 개발되었을 때 자주 발생합니다. URI의 네이밍이 명확하지 않으며, 일관되지 않은 동사/명사 혼용으로 인해 API의 목적을 직관적으로 파악하기 어렵습니다.
✅ 개선된 예시
RESTful한 URI 설계는 다음과 같은 규칙을 따릅니다:
- 리소스는 복수형 명사로 표현
- 행위는 HTTP 메서드로 표현
- 하위 리소스는 계층적으로 구조화
GET /users
GET /users/123
POST /users
PUT /users/123
DELETE /users/123
또한, 관계형 리소스를 계층적으로 표현할 수 있습니다. 예를 들어, 특정 사용자의 게시글이나 댓글 등은 다음과 같이 표현할 수 있습니다:
GET /users/123/posts
GET /users/123/comments
📌 URI 네이밍 Best Practice
| 구분 | 잘못된 예 | 권장 예 |
|---|---|---|
| 복수형 명사 사용 | /user | /users |
| 동사 사용 금지 | /getUser | /users/{id} |
| 계층적 구조 | /commentsByUser | /users/{id}/comments |
URI 설계의 일관성은 단지 ‘보기 좋게 만드는’ 것이 아닙니다. 그것은 API 사용자에게 신뢰를 주고, 유지보수와 확장을 용이하게 하는 핵심 설계 원칙입니다. 개발 초기부터 명확한 URI 네이밍 전략을 수립하고 팀 내에서 공유하는 것이 바람직합니다.
3.4 상태코드의 오남용 혹은 무시
HTTP 상태코드는 서버가 클라이언트의 요청에 대해 어떤 결과를 반환했는지를 나타내는 공식적인 언어입니다. RESTful API에서는 이 상태코드를 통해 요청의 성공, 실패, 오류의 원인 등을 전달함으로써 클라이언트와의 명확한 커뮤니케이션을 가능하게 합니다.
하지만 많은 API들이 다음과 같은 문제를 가지고 있습니다:
- 모든 요청에
200 OK만 반환 - 에러 상황에서도 HTTP 상태코드는 그대로 두고, 응답 메시지에만 오류 설명
- 상태코드를 과하게 복잡하게 사용하거나, 의미에 맞지 않게 사용
🚫 잘못된 예시
HTTP/1.1 200 OK
{
"status": "error",
"message": "사용자를 찾을 수 없습니다."
}
상태코드는 200 OK를 반환했지만, 실제 응답 본문은 에러 메시지를 담고 있습니다. 이 방식은 클라이언트가 오류 여부를 판단하기 어렵게 만들며, 특히 HTTP 상태코드를 기반으로 로직을 처리하는 애플리케이션에서는 심각한 오류를 유발할 수 있습니다.
✅ 개선된 예시
HTTP/1.1 404 Not Found
{
"error": "UserNotFound",
"message": "해당 ID의 사용자가 존재하지 않습니다."
}
위처럼 응답 본문과 상태코드가 일치하는 방식이 RESTful한 설계이며, 클라이언트는 상태코드만으로도 오류 발생 여부와 유형을 파악할 수 있습니다.
📌 주요 HTTP 상태코드 요약
| 코드 | 의미 | 사용 예시 |
|---|---|---|
| 200 OK | 요청 성공 (기본 응답) | GET, PUT 요청 등에서 성공 시 |
| 201 Created | 자원 생성 성공 | POST 요청으로 새 리소스 생성 시 |
| 204 No Content | 응답 본문 없이 성공 | DELETE 성공 시 응답 본문 생략 |
| 400 Bad Request | 클라이언트 요청 오류 | 유효성 검증 실패, 파라미터 누락 |
| 401 Unauthorized | 인증 필요 | 로그인이 필요한 요청 |
| 403 Forbidden | 접근 권한 없음 | 인증은 되었으나 권한 없음 |
| 404 Not Found | 리소스를 찾을 수 없음 | 존재하지 않는 사용자 ID 등 |
| 500 Internal Server Error | 서버 내부 오류 | 예외 처리 누락, 서버 오류 |
🔑 상태코드는 API의 신뢰성이다
HTTP 상태코드는 단순한 숫자가 아닙니다. 그것은 API의 신뢰성과 예측 가능성을 높여주는 언어이며, 클라이언트와 서버가 상호 작용하는 데 있어 가장 기본적인 ‘계약 조건’입니다.
RESTful API를 설계할 때는 상태코드를 설계의 후순위가 아니라 **의도적으로 명확히 정의해야 할 요소**로 인식하고, 에러 상황별로 어떤 코드와 메시지를 반환할 것인지 미리 정리해 두는 것이 중요합니다.
3.5 과도한 중첩 리소스 설계
RESTful API에서 자원 간의 계층 관계를 표현하는 것은 매우 자연스럽고 유용한 접근입니다. 예를 들어, 특정 사용자에게 속한 게시글이나 댓글을 URI에 구조적으로 표현하는 것은 자원의 소속성과 맥락을 명확히 전달할 수 있기 때문입니다.
하지만 이 계층 구조가 지나치게 깊어지면 오히려 API의 사용성과 유지보수성을 해치는 결과를 낳을 수 있습니다. 특히 다음과 같은 경우 문제가 발생합니다:
- 5단계 이상의 깊은 중첩 구조
- 필요 이상으로 상위 리소스를 요구하는 URI
- 실제 사용 시 상위 리소스와의 관계가 불필요한 상황
🚫 과도하게 중첩된 URI 예시
GET /users/123/posts/456/comments/789/likes/321
이러한 URI는 데이터를 찾기 위한 모든 상위 리소스의 ID를 요구합니다. 실제로는 ‘좋아요’ 정보만 필요할 뿐인데도, 사용자 ID부터 댓글 ID까지 모두 알아야 합니다. 이는 클라이언트 구현을 복잡하게 만들고, API 재사용성을 떨어뜨립니다.
✅ 개선된 예시
GET /likes/321
리소스의 고유 ID가 있는 경우에는 **중첩을 피하고 평평한 구조로 표현**하는 것이 더 RESTful하며, URI가 단순해지고, 이해와 사용이 쉬워집니다. 물론, 리소스 간의 종속성을 표현해야 할 필요가 있다면, 다음과 같은 수준의 적절한 중첩은 가능합니다:
GET /posts/456/comments
POST /posts/456/comments
이 경우는 댓글이 어떤 게시글에 속해 있는지를 표현하며, 자연스럽고 유의미한 계층 표현입니다. 하지만 그 이상은 자원의 독립성을 해칠 수 있습니다.
📌 중첩 구조 설계 기준
| 중첩 수준 | 예시 | 설명 |
|---|---|---|
| 1단계 | /users/123 | 단일 리소스 접근 |
| 2단계 | /users/123/posts | 관계 리소스 표현 가능 |
| 3단계 이상 | /users/123/posts/456/comments/789 | 불필요한 깊이는 피해야 함 |
🔑 중첩은 “표현”이지 “강제”가 아니다
RESTful URI는 자원 간의 관계를 표현하는 수단이지, 데이터 접근을 제한하거나 복잡하게 만들기 위한 장벽이 아닙니다. 설계 시에는 항상 “이 URI를 클라이언트가 쉽게 사용할 수 있는가?”를 기준으로 판단하고, 과도한 중첩은 피하도록 해야 합니다.
3.6 필터링, 정렬, 페이지네이션의 부적절한 처리
RESTful API에서 리소스 목록을 조회할 때 필터링, 정렬, 페이지네이션은 사용자 경험과 성능을 좌우하는 핵심 요소입니다. 그러나 이를 URI 경로로 처리하거나, 비표준적인 파라미터 명을 사용하는 등 REST 원칙과는 거리가 먼 방식으로 구현하는 사례가 많습니다.
다음은 실무에서 자주 나타나는 비RESTful한 설계입니다:
🚫 잘못된 예시
GET /users/filterByAge/30
GET /users/sortByName/desc
GET /users/page/2/limit/10
위 URI들은 필터링이나 정렬 정보를 리소스 경로에 포함하고 있어, URI 구조가 복잡해지고, 표준화된 클라이언트 요청과의 호환성이 낮아집니다. REST에서는 이러한 동적 쿼리는 Query String 파라미터로 처리하는 것이 바람직합니다.
✅ RESTful한 설계 예시
GET /users?age=30
GET /users?sort=name&order=desc
GET /users?page=2&limit=10
GET /users?age=30&sort=name&order=asc&page=1&limit=20
이와 같이 Query String을 사용하면 다양한 조건을 조합하여 호출할 수 있으며, 클라이언트는 필요에 따라 필터링과 정렬 기준을 유연하게 제어할 수 있습니다.
📌 Query Parameter 사용 시 권장 규칙
| 구분 | 파라미터 | 의미 |
|---|---|---|
| 필터링 | ?status=active | ‘active’ 상태의 리소스만 조회 |
| 정렬 | ?sort=name&order=asc | 이름 기준 오름차순 정렬 |
| 페이지네이션 | ?page=3&limit=25 | 3페이지, 25개 단위 조회 |
📊 응답에 포함해야 할 메타 정보
페이징이나 정렬이 적용된 결과에서는 응답 본문에 다음과 같은 메타 데이터를 포함하는 것이 좋습니다:
{
"data": [...],
"meta": {
"page": 2,
"limit": 10,
"totalPages": 5,
"totalItems": 50
}
}
이러한 응답 구조는 클라이언트가 다음 페이지를 계산하거나, 전체 데이터를 기반으로 UI를 구성하는 데 유리합니다. 특히 SPA 또는 모바일 앱에서 유용합니다.
🔑 핵심 정리
RESTful API는 ‘자원 중심’으로 설계되되, 리스트 조회와 같은 복합 조건의 요청은 URI 경로가 아닌 **Query String으로 처리**해야 합니다. 표준화된 파라미터 이름을 사용하는 습관은 API의 일관성과 문서화 품질을 높이는 중요한 전략입니다.
3.7 에러 응답이 불친절한 경우
RESTful API를 사용하는 클라이언트는 다양한 상황에서 오류에 직면하게 됩니다. 그러나 많은 API들이 에러 발생 시 불친절한 응답을 반환하거나, 단순한 문자열 메시지로만 오류를 설명함으로써 클라이언트 개발자가 문제를 진단하고 해결하는 데 큰 어려움을 겪게 만듭니다.
에러 응답은 단순한 로그 메시지가 아닙니다. 그것은 API 사용자(클라이언트)에게 제공되는 **문서화된 가이드라인**이어야 하며, 프로그램이 오류 상황을 예측하고 자동으로 대응할 수 있는 구조를 갖춰야 합니다.
🚫 불친절한 에러 응답 예시
{
"message": "Something went wrong"
}
이런 에러 메시지는 사람에게도, 프로그램에게도 의미 있는 정보를 제공하지 못합니다. 무엇이, 왜, 어떤 위치에서 잘못되었는지 알 수 없습니다.
✅ 구조화된 에러 응답 예시
{
"error": {
"code": "USER_NOT_FOUND",
"message": "해당 ID의 사용자를 찾을 수 없습니다.",
"details": {
"userId": "123"
},
"timestamp": "2025-04-17T10:21:00Z"
}
}
이처럼 구조화된 에러 응답은 오류의 코드, 메시지, 관련 정보, 발생 시각 등을 포함함으로써 클라이언트가 다음과 같은 이점을 누릴 수 있습니다:
- 에러 코드에 따른 자동화된 처리 (e.g.
USER_NOT_FOUND→ 사용자 등록 유도) - 로그 및 모니터링 시스템과의 연동 용이
- 디버깅 시 정확한 원인 추적 가능
📌 에러 응답의 설계 요소
| 필드 | 설명 |
|---|---|
| code | 에러 식별을 위한 고유 코드 (예: INVALID_PARAMETER) |
| message | 사용자에게 보여줄 수 있는 간결한 메시지 |
| details | 필드 오류, 파라미터 문제 등 상세 설명 |
| timestamp | 오류 발생 시각 (ISO 8601 형식 권장) |
🔐 보안 측면 고려 사항
에러 메시지를 너무 상세히 노출하면 악의적인 사용자에게 정보를 제공하는 결과를 초래할 수 있습니다. 예를 들어, 인증 실패 시 비밀번호가 틀렸습니다보다는 로그인 정보가 올바르지 않습니다와 같이 **모호하지만 충분히 유효한 메시지**를 사용하는 것이 좋습니다.
🔑 핵심 정리
에러 응답은 단순한 예외 메시지가 아닌, 클라이언트 개발자와 사용자 모두에게 문제를 정확히 설명하고 해결로 이끄는 가이드여야 합니다. 잘 설계된 에러 포맷은 개발자 경험을 극적으로 개선하며, API 신뢰도 향상에도 큰 영향을 미칩니다.
3.8 버전 관리의 부재
API는 시간이 지나면서 요구사항이 바뀌고, 기능이 추가되며, 기존의 구조를 변경해야 하는 상황이 빈번하게 발생합니다. 이때 명확한 버전 관리 전략이 없다면 클라이언트는 예기치 않은 오류에 노출되고, 기존 사용자와의 계약이 깨지는 결과를 초래할 수 있습니다.
RESTful API 설계에서 버전 관리는 선택이 아닌 필수입니다. 특히 다수의 외부 개발자나 다양한 플랫폼에서 사용하는 API라면, 변경 이력과 호환성 유지를 위한 버전 명시는 절대적으로 필요합니다.
🚫 버전 없이 설계된 API 예시
GET /users
처음에는 잘 작동하더라도, 구조가 변경되거나 필드가 바뀌면 클라이언트는 혼란을 겪게 됩니다. 특히 기존 기능을 그대로 사용하는 클라이언트는 예외 없이 영향을 받게 되죠.
✅ URI 기반 버전 관리 예시
GET /v1/users
GET /v2/users
이 방식은 가장 널리 사용되며, 클라이언트가 명확히 어느 버전을 호출하고 있는지 URI 자체로 구분할 수 있어 유지보수가 간편합니다. 다만 URI가 변경되므로 문서화나 라우팅 관리에서 버전별 분리가 필요합니다.
✅ 헤더 기반 버전 관리 예시
GET /users
Accept: application/vnd.example.v2+json
HTTP 헤더 기반 버전 관리 방식은 URI를 깔끔하게 유지하면서도 버전을 구분할 수 있는 장점이 있습니다. 주로 대규모 API 플랫폼이나 데이터 포맷의 다변화를 요구하는 서비스에서 채택합니다. 그러나 구현과 테스트, 문서화가 상대적으로 복잡할 수 있으며, 일부 클라이언트(특히 브라우저)에서는 사용이 제한될 수 있습니다.
📌 버전 관리 전략 비교
| 구분 | URI 버전 방식 | 헤더 버전 방식 |
|---|---|---|
| 표현 방식 | /v1/resource | Accept: application/vnd.name.v1+json |
| 가시성 | 높음 (URL에서 즉시 확인 가능) | 낮음 (헤더를 열어야 확인 가능) |
| 문서화 | 간단 (Swagger 등과 잘 호환) | 복잡 (버전마다 문서 분리 필요) |
| 클라이언트 호환성 | 높음 | 일부 제한 (브라우저 캐싱 문제 등) |
📈 마이그레이션 전략
기존 클라이언트가 API를 사용 중인 상황에서 무작정 새로운 버전으로 변경하는 것은 바람직하지 않습니다. 다음과 같은 마이그레이션 전략을 병행하는 것이 좋습니다:
- 이전 버전은 일정 기간 동안 유지 (deprecation notice 포함)
- 버전별 문서와 예제 제공
- 로그 기반으로 구버전 사용 현황 파악 후 단계적 종료
🔑 핵심 정리
API 버전 관리는 **계약의 유효성을 유지하기 위한 필수 전략**입니다. 명확한 버전 체계를 갖추고, 구조 변경이 필요한 시점에는 새로운 버전을 도입함으로써 클라이언트와의 신뢰를 지킬 수 있습니다. RESTful API의 생명주기를 고려할 때, 버전 전략은 반드시 초기 설계 단계부터 포함되어야 할 핵심 요소입니다.
4. 실제 사례 분석: 잘못된 API 설계 vs 개선된 API 설계
이전까지는 RESTful API 설계에서 자주 발생하는 실수를 항목별로 살펴보았습니다. 이번에는 실제 사례를 통해 잘못된 API 구조가 어떻게 사용자 경험을 저해하고 유지보수에 부담을 주는지를 확인하고, 이를 RESTful한 방식으로 어떻게 개선할 수 있는지를 구체적으로 비교해보겠습니다.
📌 시나리오 개요 – A사의 회원 정보 API
A사는 사내 포털 시스템에 REST API를 도입하여 웹/모바일 클라이언트와 통신하도록 구성하였습니다. 그러나 빠른 개발 과정에서 RESTful 설계 원칙이 무시된 결과, 다음과 같은 문제를 겪고 있었습니다.
🚫 기존 API 구조 (비RESTful 설계)
GET /getUserInfoById?id=123
POST /insertNewUser
POST /updateUserInfo
POST /deleteUser
이 API는 다음과 같은 문제를 내포하고 있었습니다:
- URI가 동사형으로 설계되어 있어 리소스 개념이 모호함
- 모든 작업이 POST로 처리되어 멱등성과 의미 구분이 없음
- 상태코드가 항상
200 OK로 반환되어 클라이언트의 오류 대응이 불가능
✅ 개선된 API 구조 (RESTful 설계)
GET /users/123
POST /users
PUT /users/123
DELETE /users/123
개선된 구조는 REST의 기본 원칙에 따라 설계되었으며, 다음과 같은 장점을 제공합니다:
- URI는 명확한 자원을 식별하며, HTTP 메서드를 통해 행위를 표현
- 멱등성 보장: 동일한 요청 반복 시 결과 일관성 유지
- 상태코드와 에러 메시지를 분리: 클라이언트는 응답을 기준으로 오류를 처리할 수 있음
📄 응답 예시: 사용자 정보 조회 (200 OK)
{
"id": 123,
"name": "김개발",
"email": "dev.kim@example.com",
"role": "admin"
}
📄 응답 예시: 사용자 미존재 (404 Not Found)
{
"error": {
"code": "USER_NOT_FOUND",
"message": "ID가 123인 사용자를 찾을 수 없습니다."
}
}
📊 설계 비교 요약
| 항목 | 비RESTful 설계 | RESTful 설계 |
|---|---|---|
| URI 구조 | /getUserInfoById | /users/123 |
| 메서드 사용 | 모든 작업 POST | GET/POST/PUT/DELETE 분리 |
| 상태코드 | 항상 200 | 상황별 적절한 상태코드 |
| 클라이언트 이해도 | 직관성 부족 | 명확하고 예측 가능 |
🔍 결론
RESTful API 설계는 단순히 “멋져 보이는 URL”을 만드는 것이 아닙니다. 그것은 **사용자 경험, 유지보수, 명확한 커뮤니케이션을 동시에 고려한 설계 철학**입니다. A사의 사례처럼, 잘못된 API 구조는 기능적으로는 작동하더라도 장기적으로는 팀 전체의 생산성과 품질에 큰 영향을 끼칠 수 있습니다.
API는 내부 시스템을 위한 도구가 아니라, 외부 사용자와 시스템 간의 신뢰를 형성하는 계약입니다. 따라서 REST의 원칙을 따르는 명확하고 예측 가능한 설계를 지향해야 합니다.
5. RESTful API 설계를 위한 Best Practices
앞서 살펴본 다양한 오류들은 대부분 기본 원칙의 누락 또는 일관성의 결여에서 비롯됩니다. 이 장에서는 실무에서 RESTful API를 안정적이고 확장 가능하게 설계하기 위해 반드시 알아두어야 할 Best Practice들을 종합적으로 정리합니다.
📌 1. URI 설계 원칙
- 자원은 복수형 명사로 표현 (
/users,/products) - 동작은 URI에 표현하지 말고 HTTP 메서드로 표현
- 계층적 리소스는 하위 자원으로 구성 (
/users/123/posts) - 리소스의 ID는 경로 파라미터로 명확히 구분
- 필터링, 정렬, 페이지네이션은 쿼리 파라미터로 처리
📌 2. HTTP 메서드와 동작 매핑
| 메서드 | 기능 | 설명 |
|---|---|---|
| GET | 조회 | 리소스 상태 확인 (안전, 멱등) |
| POST | 생성 | 새 리소스 생성 (비멱등) |
| PUT | 전체 수정 | 지정 리소스 전체 대체 (멱등) |
| PATCH | 부분 수정 | 리소스 일부분 수정 (비멱등 가능) |
| DELETE | 삭제 | 리소스 제거 (멱등) |
📌 3. 에러 응답 구조화
- 상태코드는 의미에 맞게 정확히 반환 (200, 201, 400, 404, 500 등)
- 응답은
error.code,error.message,details등의 구조로 제공 - 에러 메시지는 사용자/개발자 모두 이해 가능한 언어로 작성
- 보안 이슈가 되는 상세 정보는 숨김
📌 4. API 버전 전략 수립
- URI 기반 버전 관리: /v1/resource (가시성 좋음, 구현 간편)
- 헤더 기반 버전 관리: Accept 헤더로 제어 (유연성 높음, 복잡함)
- 구버전은 점진적 Deprecation 전략으로 단계적으로 종료
📌 5. 문서화 및 스펙 자동화
- API 명세는 Swagger/OpenAPI와 같은 표준 도구로 관리
- 요청/응답 예시, 상태코드, 에러 응답 구조 포함
- API 변경 시 문서 자동 갱신 체계 마련
📌 6. 인증과 권한 부여
- JWT, OAuth2 등 표준 인증 방식 채택
- 권한에 따른 리소스 접근 제어를 API 레벨에서 처리
- 인증 실패와 권한 없음(401/403)을 명확히 구분
📌 7. 응답 성능과 캐싱 전략
- 정적 리소스에 대해 Cache-Control, ETag 헤더 사용
- 대용량 조회 시 페이지네이션과 제한(limit) 필수
- 필터링/정렬 쿼리는 인덱싱 전략과 함께 고려
🔑 마무리 정리
RESTful API의 성공은 단순히 문법이나 규칙을 지키는 것이 아니라, 명확한 철학과 일관된 구조, 그리고 사용자 경험을 고려한 세심한 설계에서 비롯됩니다. 위에 제시된 Best Practices를 참고하여, 누구나 예측 가능하고 신뢰할 수 있는 API를 설계해 보시기 바랍니다.
6. 결론: API는 하나의 계약(Contract)이다
RESTful API는 단순히 데이터를 주고받는 인터페이스가 아닙니다. 그것은 시스템 간 신뢰를 기반으로 한 계약이며, 개발자 간 약속입니다. 이 계약이 명확할수록, 클라이언트와 서버는 서로에 대한 예측 가능성을 확보하게 되고, 시스템은 더욱 견고하고 확장 가능해집니다.
이번 글에서는 RESTful API 설계에서 자주 발생하는 실수 8가지를 실제 사례와 함께 살펴보고, 이를 해결하기 위한 Best Practice를 체계적으로 정리했습니다. 특히 잘못된 URI 설계, HTTP 메서드의 오용, 비구조적인 에러 응답, 버전 관리 누락 등은 단순한 실수가 아니라, 사용자 경험과 API 신뢰성에 직결되는 중대한 설계 문제임을 강조하고자 했습니다.
REST는 ‘표현(Representation)’과 ‘상태(State)’에 대한 일관된 정의를 통해, 자원의 설계와 클라이언트의 행동을 규정짓는 철학입니다. 이 철학을 온전히 이해하고 실천하는 것이 진정한 RESTful 설계의 시작입니다.
당신이 만드는 API는 문서보다 먼저 읽히고, UI보다 먼저 경험됩니다. 클라이언트 개발자와 API 사용자에게 **직관적이고 예측 가능한 경험**을 제공하는 API는 결국 그 자체가 제품의 품질이자 브랜드가 됩니다.
🔑 마지막 메시지
좋은 API는 보이지 않아야 합니다. 사용자가 문서를 보지 않아도 감을 잡을 수 있고, 예외 상황에서도 당황하지 않으며, 개발자가 설계자의 의도를 자연스럽게 이해할 수 있다면, 그것이 바로 RESTful API 설계의 궁극적인 목표입니다.
지금 이 순간에도, 누군가는 당신의 API를 통해 제품을 만들고 있습니다. 그들에게 신뢰받는 파트너가 되기 위한 첫걸음은, 바로 오늘 설계하는 API 한 줄에서 시작됩니다.