RESTful API 설계 시 꼭 알아야 할 핵심 개념 정리
Soft Delete, Control URI, REST 원칙, HATEOAS까지
서비스를 개발하다 보면 단순 CRUD 이상의 다양한 상태 변화, 논리 삭제, 버전 관리 등 복잡한 상황을 마주하게 된다.
이 글에서는 RESTful API를 설계할 때 반드시 알아야 할 핵심 개념들을 하나씩 정리했다.
🌝 Soft Delete란?
데이터를 실제로 삭제하지 않고, 삭제된 것처럼만 표시하는 방식이다.
즉, DB에서 지우지 않고 deleted_at 또는 is_deleted 같은 필드에 값을 넣어서 “삭제된 상태”로 간주한다.
✔ 예시
UPDATE users SET deleted_at = NOW() WHERE id = 1;✔ 어떤 HTTP Method를 사용해야 할까?
DELETE /users/1클라이언트 입장에서는 “이 유저를 삭제한다”는 의도만 표현하면 된다.
실제로 물리 삭제인지 소프트 삭제인지는 서버의 정책에 따라 결정된다.
🕹️ Control URI란?
단순 CRUD가 아닌, 특정 행위 중심의 작업을 수행할 때 사용하는 API 경로이다.
컨트롤 URI는 명사형이 아닌, 명령(동사) 중심의 URI를 의미하며 일반적으로 POST와 함께 사용된다.
POST /users/10/ban
POST /orders/1234/cancel
POST /user-missions/345/approve
POST /user-missions/345/reject✔ 언제 사용하면 좋을까?
특정 리소스의 상태를 변화시키는 비즈니스 로직일 때
PATCH나 PUT으로 상태값을 직접 수정하는 것이 어색하거나 비직관적일 때
예: ‘승인하기’, ‘거절하기’, ‘활성화하기’, ‘정지시키기’ 등
🪟 RESTful API 설계 핵심 요약 (출처: Azure 아키텍처 센터)
1. REST란?
REST는 Representational State Transfer의 약자로, HTTP 기반 분산 시스템 아키텍처 스타일입니다.
HTTP 메서드(GET, POST, PUT, DELETE 등)와 JSON 같은 표현 방식을 사용하여 상태 비저장 방식으로 리소스를 다룹니다.
2. API는 리소스 중심으로 구성하자
http
복사
편집
✅ Good: /orders
❌ Bad: /create-order
URI는 명사형으로 설계하고, 동사는 HTTP 메서드에 맡기세요.
3. HTTP 메서드 의미대로 사용
Method 의미
GET 리소스 조회
POST 새 리소스 생성 또는 명령 수행
PUT 리소스 전체 대체 (또는 생성)
PATCH 리소스 부분 수정
DELETE 리소스 삭제 (Soft Delete 포함)
HATEOAS란?
Hypertext As The Engine Of Application State의 약자로,
응답에 관련 리소스의 링크를 포함하여 클라이언트가 다음 행동을 예측 가능하게 만드는 원칙입니다.
{
"orderId": 3,
"product": "국밥",
"quantity": 2,
"links": [
{
"rel": "self",
"href": "https://example.com/orders/3",
"method": "GET"
},
{
"rel": "cancel",
"href": "https://example.com/orders/3",
"method": "DELETE"
},
{
"rel": "update",
"href": "https://example.com/orders/3",
"method": "PUT"
}
]
}✔ 실무에서는?
HATEOAS 구현이 번거롭고, 실제로는 Swagger 같은 API 명세 툴을 활용하는 경우가 많다.
하지만 REST 이론적으로는 레벨 3(최고 수준)의 REST API가 되기 위한 핵심 요소이다.
API 버전 관리 전략
/v1/orders ← URI 버전 관리
/orders?version=1 ← 쿼리 파라미터 버전 관리
Custom-Header: api-version=1 ← 헤더 버전 관리
Accept: application/vnd.myapi.v1+json ← 미디어 타입 기반버전 관리는 반드시 도입되어야 하며, 서비스 특성에 맞는 방식을 선택해야 한다.
필터링, 페이징, 정렬은 Query String 활용
GET /orders?minCost=1000&limit=20&offset=40
필터링, 정렬, 페이지네이션을 서버에서 처리하여 클라이언트 부담을 줄이고 성능을 높일 수 있다..
응답 코드 정리
| 메서드 | 상태 코드 | 의미 |
|---|---|---|
| GET | 200 | 조회 성공 |
| POST | 201 | 생성 성공 |
| PUT / PATCH | 200 / 204 | 업데이트 성공 |
| DELETE | 204 | 삭제 성공 |
| 오류 | 400, 404, 409 등 | 클라이언트/서버 오류 |
비동기 작업은 202 Accepted
HTTP/1.1 202 Accepted
Location: /api/status/12345
장기 작업은 즉시 응답하지 않고 상태 확인용 엔드포인트를 제공해야 한다.
🤔마무리
RESTful API는 단순히 CRUD에만 국한되지 않으며
리소스 중심 설계, 의미 있는 URI 구성, 명확한 상태 코드, 유연한 버전 관리 등을 통해
확장 가능하고 유지보수하기 좋은 API를 만들 수 있다.
특히 HATEOAS, API 명세 버전관리 등.. 중요한 점에 대해서 다시 배운 느낌.
