REST API의 Richardson Maturity Model Backend/Spring, ETC2026. 5. 24. 22:18
Intro
: 2008년 QCon(link)에서 Leonard Richardson은 개발자들이 만든 API가 REST를 준수하는지, 적합한지를 4단계로 분류하는 `성숙도 모델 - RMM(Richardson Maturity Model)`이라는 것을 발표했었습니다.
Level 0에서 Level 3까지 총 4단계로 분류되며, Level 3은 적용하기 상당히 불편하며 Over-Engineering으로 취급되는 편입니다. Level 2까지만 적용해도 충분히 좋은 REST API라고 취급되니 이정도를 목표로 삼으면 될 것 같아요.
Level 0
: URL이 행위 중심으로 이루어지는 단계라고 볼 수 있겠습니다. HTTP 위에 RPC를 얹은 것에 가까운데, 다음과 같은 느낌입니다.
/createUser
/deleteUser
/getUser
/updateUser
HTTP Method를 그다지 활용하지 않으며, 행위가 API Model의 중심이 됩니다.
Level 1
: URL이 명사, resource 중심으로 이루어지는 단계입니다. 무엇(resource)을 다루고 있나?가 API Model의 중심이 되는데, 다음과 같은 느낌입니다.
/users
/users/1
/orders/1
하지만 이 단계에서도 HTTP Method를 그다지 활용하지 않아요.
Level 2
: URL은 resource를 표현하고, HTTP Method로 action을 표현하는 단계입니다. 이걸 HTTP semantic을 활용한다고 표현하기도 해요. 다음과 같은 느낌입니다.
GET /users/1
POST /users
PUT /users/1
DELETE /users/1
Level 3 : HATEOAS(Hypermedia As The Engine Of Application State)
: 현재 state에서 client가 다음에 전이(transition)할 수 있는 state를 hypermedia link로 제공하는 단계입니다. API를 호출하면 resource에 할 수 있는 action들이 response에 포함되게 됩니다. 다음과 같은 response를 예시로 들 수 있겠습니다.
{
"orderId": 1,
"status": "PROCESSING",
"_links": {
"self": { "href": "/orders/123" },
"cancel": { "href": "/orders/123/cancel", "method": "DELETE" },
"payment": { "href": "/orders/123/payment", "method": "POST" }
}
}
response에서 _links를 보고 다음에 호출할 수 있는 action, 다음에 전이할 수 있는 state를 결정할 수 있습니다. orderId: 1에 해당하는 resource를 대상으로 할 수 있는 것들입니다. 적용하는게 상당히 불편하기도 해서 Level 3까지 적용하는 경우는 잘 없는데, 그래도 장단점은 존재합니다.
장점
- Client-Server간 결합도를 낮출 수 있습니다.
- API 구조 변경이 편합니다.
- Dynamic하게 Workflow를 변경할 수 있습니다.
단점
- Frontend와 협업이 까다로워질 수 있습니다
: HATEOAS는 FSM(Finite State Machine) 기반의 상태 전이인데, 보통 Service의 UX는 Frontend가 주관하는게 일반적이에요. UX에 주는 영향까지 고려해서 _links 같은 것들을 결정하는 것은 어렵지 않을까요? - 개발 환경에서의 지원이 어려움
: Swagger 같은 것들은 정적인 Endpoint를 기반으로 해서 동적인 Endpoint와는 잘 맞지 않습니다. 비슷한 이유로 Code Generation도 어려워요. 어떤 Endpoint를 사용할 수 있는지가 알기 어려우니까요. - Caching, CDN, prefetch 같은 것들도 전략을 세우기 어려움.
: HATEOAS에서는 Client가 주도하는 최적화가 어렵습니다. 사용할 수 있는 Endpoint를 확정할 수가 없으니, prefetch 하려면 너무 많은 case를 고려해야 합니다. CDN도 같은 URL, Header인데 response가 달라질 수 있으므로 활용이 어렵겠죠. Caching도 마찬가지 입니다.
※ Hypermedia link?
: Level 3에서 다음에 전이할 수 있는 state, 할 수 있는 action을 hypermedia link로 제공한다고 처음에 이야기했었어요. 그냥 url, api path, endpoint라고 표현해도 될텐데 왜 Hypermedia link라고 표현했을까요?
Hypermedia는 link를 통해 연결된 media를 뜻합니다. HTML은 link, action(같은 것으로...)을 담고있는 Hypermedia 문서라고 볼 수 있어요. Browser는 HTML 안에 있는 link, action 같은 것에 따라 다음 state로 전이할 수 있다고 볼 수 있습니다. Roy Fielding은 REST API에서도 Hypermedia를 통해 다음 상태로 전이할 수 있길 원했습니다. 그래서 Hypermedia link를 제공한다고 표현한 것이고... 또, 단순 url이라고 하기에는 "method": "DELETE"와 같이 method가 포함되어 있기도 하죠(api endpoint만으로 method를 추측할 수 있다면 method는 없어도 됩니다).
Reference
'Backend > Spring, ETC' 카테고리의 다른 글
| kotlin.test.Test vs jupiter.api.Test (0) | 2025.10.25 |
|---|
