REST - 상태 등 세부 컬럼 수정 엔드포인트 (End-point) 설계

예시

어떤 엔터티에 대한 한 가지 컬럼에 대해서만 수정할 때 엔드포인트 설계를 어떻게 하면 좋을까요?

 

가령 어떤 품목(product)에 대한 예약(reservation)이 있다고 가정합니다.

예약(reservation)에는 승인 대기, 승인 완료, 반납 완료 - 총 3가지 상태가 있다고 가정합니다.

 

이런 세부 상태 등 하나의 컬럼을 변경하는 API를 설계하는 방법들에 대해서 알아보겠습니다.

 

uri 비교

떠오르는 방법은 아래 5가지가 있습니다.

1. PUT /bookings/{id}
2. PATCH /bookings/{id}
3. PUT /bookings/{id}/status
4. PATCH /bookings/{id}/status
5. POST /bookings/{id}/approve + POST /bookings/{id}/return

우선 1,2 번 같은 경우 uri가 적절하지 않습니다. 물론 구현하는데 훨씬 쉽겠죠.

컨트롤러 메서드(Controller method)에서 예약 엔터티에 관한 어떤 수정 요청이 들어오든 /bookings/{id}에서 이루어질 수 있습니다.

 

이 방법은 효율이 안좋고 type-safe하지 않습니다.

원하는 수정요소가 많고 어떤 것이 파라미터로 들어오는지에 따라 다르게 동작하려면 많은 자원이 소모됩니다. status 컬럼이나 테이블의 경우, 일반적인 수정사항과 성격이 다르고, 다른 컬럼에 종속적이지 않으며 일반적인 예약 수정과는 거리가 있는 사항입니다.

 

그리고 상태 변경 같은 경우에는 관리자만 할 수 있는 항목입니다. 그러면 일반적인 사항이 파라미터로 들어오면 권한 제한을 사용자로 걸고, 파라미터로 status가 들어오면 권한 제한을 관리자로 건다?.. 벌써 복잡합니다.

따로 uri를 한번 더 두는 것이 바람직합니다.

 

 

5번의 경우는 의미 없이 복잡합니다. REST API에서 수정으로 PUT이나 PATCH를 사용할 수 있는데, 굳이 동사형 POST로 2개로 분리시킬 이유가 없습니다. 만약 상태가 3가지가 아니라 예를 들어 승인대기, 승인완료 두 가지였으면 고민해볼 만 합니다.

 

PUT vs PATCH

그러면 남은 건 3번과 4번인데 PUT과 PATCH를 선택하는 기준은 수정할 범위에 있습니다.

 

PUT은 전체를 수정

PATCH는 일부를 수정

 

즉, uri를 bookings/{id}/status로 했다면 대상인 자원은 status가 됩니다.

 

예를 든 status는 예약에 있는 하나에 컬럼입니다. PUT을 쓰는 것이 적절합니다. 하나의 컬럼이 대상이고 이를 수정하는 것은 전체이기 때문이죠.

 

만약 status를 하나의 컬럼으로 보지 않고, 예약에 자식 관계 테이블이라면 PUT, PATCH 어떤 것을 사용해도 상관 없습니다.

 

PUT을 사용할 때는 변경 가능한 컬럼 중 전체 컬럼을, PATCH를 사용할 때는 변경할 컬럼만 보내게 request body만 잘 세팅한다면 말이죠.