3강. 리소스 설계보다 중요한 행위 모델링

🤔 Question

👉 REST API를 설계할 때 가장 많이 듣는 조언이 있습니다.
"리소스를 잘 나누세요."
"명사형 URI로 만드세요."

그래서 많은 개발자가
URI 설계에만 모든 에너지를 쏟습니다.

하지만 실무에서 진짜 문제는 다른 곳에서 발생합니다.
👉 리소스보다 더 중요한 것은 '행위(Behavior)' 모델링입니다.

 

🎯 리소스만 잘 나누면 충분할까?

보통 주문 시스템을 만들면 이렇게 설계합니다.

GET /orders/{id}
POST /orders
PUT /orders/{id}
DELETE /orders/{id}

교과서적으로는 완벽해 보입니다.
하지만 비즈니스는 곧 묻습니다.

"주문을 취소하고 싶어요."
"결제를 승인해야 해요."
"배송을 시작해야 합니다."

이때 개발자는 고민합니다.
👉 이걸 어디에 어떻게 넣어야 하지?

 

🎯 실무에서 흔히 등장하는 URI

POST /orders/{id}/cancel
POST /orders/{id}/approve
POST /orders/{id}/ship

어딘가 REST 원칙을 위반한 것 같지만
현실에서는 가장 많이 쓰이는 형태입니다.

왜 그럴까요?
👉 비즈니스는 단순한 CRUD가 아니라 '상태 변화 행위'의 연속이기 때문입니다.

 

🎯 리소스 중심 사고의 한계

리소스 중심 설계는
"데이터 저장 구조"를 기준으로 합니다.

하지만 사용자는 데이터를 원하지 않습니다.
👉 사용자는 '일을 처리해주길' 원합니다.

✔ 주문을 취소해줘
✔ 결제를 승인해줘
✔ 배송을 시작해줘

이것이 바로 행위입니다.
REST API는 결국
행위를 안전하게 계약으로 표현하는 일입니다.

 

🎯 행위 모델링이 계약을 지킨다

행위를 명확히 모델링하면
다음이 자연스럽게 정해집니다.

✔ 어떤 상태에서 호출 가능한지
✔ 호출 후 어떤 상태로 변하는지
✔ 실패하면 어떤 에러가 오는지

즉,
👉 행위 모델링이 곧 계약(Contract)의 핵심이 됩니다.

 

🎯 좋은 설계의 기준

좋은 API 설계는
"명사 URI를 지켰는가?"가 아니라

👉 비즈니스 행위가 명확히 드러나는가?
👉 상태 변화가 예측 가능한가?
👉 소비자가 오해 없이 사용할 수 있는가?

이 세 가지로 판단해야 합니다.

 

🎯 다음 강의에서 다룰 것

행위 모델링이 정리되면
다음 단계는 계약을 실제로 고정하는 방법입니다.

다음 강의에서는
👉 API 계약을 문서가 아니라 스키마로 고정하는 방법
👉 OpenAPI와 Contract-First 개발 전략

을 다루게 됩니다.

 

☔ 정리

👉 REST는 리소스 설계만으로 완성되지 않습니다.
👉 행위 모델링이 진짜 API 계약입니다.
👉 좋은 API는 데이터를 보여주는 것이 아니라
일을 안전하게 처리하게 해주는 것입니다.

 

 

If I was of any help to you, please buy me coffee 😿😢😥

If you have any questions, please leave them in the comments

Buy me a coffee

▶ Youtube Sub

🧭 References

[1] reference : https://doctorson0309.tistory.com/

[2] Ads : https://apps.apple.com/us/app/beluga-classic-film-filters/id6744041061