꼬리가 몸통을 흔든다 - RESTful 한 API 설계의 숨겨진 이점에 관한 글 -

꼬리가 몸통을 흔들다(WAG THE DOG) - 서양 속담

RESTful API를 이야기할 때 우리는 주로 클라이언트 측면의 이점을 이야기합니다.
직관적인 URL 구조, HTTP 메서드의 의미론적 사용, 명확한 리소스 중심 설계 등이 API 사용자들에게 주는 이점을 강조하죠.
하지만 오늘은 다른 관점에서 RESTful API를 바라보고자 합니다.

API를 설계하고 개발하는 우리들에게 RESTful API가 어떤 가치를 주는지, 어떻게 우리의 도메인 이해를 돕는지 이야기해보려 합니다.

이는 제가 최대한 RESTful한 API를 작성해보려고 하는 과정에서, RESTful API 설계가 단순히 클라이언트에게 좋은 인터페이스를 제공하는 것 뿐 만 아니라, API를 개발하는 개발자에게 비즈니스 도메인에 대한 이해, 구조화, 체계화를 돕고, 때론 '꼬리가 몸통을 흔드는 격'으로 코드의 전체적인 구조를 더 깔끔하게 만들어 줄 수도 있다는 것을 깨달았기 때문입니다.

 

RESTful한 API에 대한 설계 원칙은 아래 글을 참고 부탁드립니다.

2024.12.12 - [기초 개념] - RESTful API란?

RESTful API란?

 

 

RESTful API 설계가 주는 통찰

RESTful API를 설계한다는 것은 단순히 엔드포인트를 만드는 작업이 아닙니다.
이는 우리의 비즈니스 도메인을 체계적으로 분석하고 구조화하는 과정입니다.
이 과정에서 우리는 다음과 같은 통찰을 얻을 수 있습니다:

1. 리소스의 계층 구조화

리소스를 URL로 표현하는 과정은 도메인 개념들 간의 관계를 명확히 정의하도록 합니다.
각 리소스가 어떤 상위 개념에 속하는지, 독립적인 개념인지, 다른 리소스의 하위 개념인지를 고민하게 되죠.

2. 도메인 개념의 명확한 분리

REST 원칙을 따르다 보면 자연스럽게 도메인 개념들이 명확히 분리됩니다.
각 리소스의 경계가 뚜렷해지고, 이는 코드 설계에도 긍정적인 영향을 미칩니다.

3. 일관된 인터페이스 설계

균일한 인터페이스 원칙을 따르면서, 우리는 시스템 전반에 걸쳐 일관된 패턴을 만들게 됩니다.
이는 코드의 예측 가능성을 높이고 유지보수를 용이하게 만듭니다.

실제 사례: 결제 시스템 API 설계

이론적인 이야기를 넘어, 제가 RESTfulAPI를 설계하던 도중 RESTful한 설계가 기존 코드의 구조와 비즈니스 도메인의 여러 개념들 간의 관계 이해와 구조화를 돕는다는걸 깨달았던 순간을 간략화한 예시입니다.

처음에 우리는 다음과 같은 결제 시스템 API 구조를 가지고 있었습니다:

/api/v1/payments
    /credits
    /cashes
    /kakao-pays
    /naver-pays

그리고 각 결제 수단별로 환불 기능을 추가하려고 했을 때, 처음에는 이렇게 설계했습니다:

/api/v1/payments/credits/refunds
/api/v1/payments/cashes/refunds
/api/v1/payments/kakao-pays/refunds
/api/v1/payments/naver-pays/refunds

하지만 이 구조를 검토하면서 머리속에 자꾸 '?' 갈고리가 걸렸습니다.
과연 환불은 신용 결제의 하위 속성이나 개념인가??
답은 '아니다' 였습니다.

'환불'이라는 개념이 각각의 결제 수단의 하위 개념이 아니라, 결제와 동등한 수준의 독립적인 비즈니스 개념이라는 것을 깨달은 것이죠.
이에 따라 구조를 다음과 같이 변경했습니다:

/api/v1/refunds
    /credits
    /cashes
    /kakao-pays
    /naver-pays

API 설계가 코드 구조에 미치는 영향

이러한 API 구조의 변경은 단순히 URL 경로의 변경으로 끝나지 않았습니다. 이는 전체 코드 구조와 도메인 모델의 변경으로 이어졌습니다:

1. UseCase 분리
   • 기존: PaymentUseCase 내에 환불 로직 포함
   • 변경: RefundUseCase로 독립적 분리
2. 비즈니스 규칙의 명확한 구분
   • 결제 관련 규칙과 환불 관련 규칙의 명확한 분리
   • 각각의 정책과 제약사항을 독립적으로 관리 가능
3. 코드의 응집도 향상
   • 환불 관련 모든 로직이 한 곳에 모임

결론

RESTful API 설계는 단순히 클라이언트를 위한 인터페이스를 만드는 것이 아닙니다.
이는 우리의 비즈니스 도메인을 더 깊이 이해하고, 체계적으로 구조화하는 과정입니다.
API 설계 과정에서 얻은 통찰은 전체 시스템 아키텍처와 코드 구조를 개선하는 데 큰 도움이 됩니다.

우리가 RESTful API를 설계할 때, 단순히 "이게 클라이언트에게 편할까?"라는 질문을 넘어서,
"이 구조가 우리의 도메인을 정확히 표현하고 있는가?"라는 질문을 던져보는 것이 중요합니다.
그렇게 함으로써 우리는 더 나은 API를 만들 수 있을 뿐만 아니라, 더 나은 시스템 구조를 만들어낼 수 있습니다.