HTTP 메서드 측면에서 API 작업 정의

HTTP 프로토콜은 요청에 의미 체계의미를 할당하는 다양한 메서드를 정의한다. 대부분의 RESTful 웹 API에서 사용하는 일반적인 HTTP 메서드는 다음과 같다.

• GET: 지정된 URI에서 리소스의 표현을 검색한다. 응답 메시지의 본문은 요청된 리소스의 세부 정보를 포함하고 있다.
• POST: 지정된 URI에 새 리소스를 만든다. 요청 메시지의 본문은 새 리소스의 세부 정보를 제공한다. 참고로 POST를 사용하여 실제로 리소스를 만들지 않는 작업을 트리거할 수도 있다.
• PUT: 지정된 URI에 리소스를 만들거나 대체한다. 요청 메시지의 본문은 만들거나 또는 업데이트할 리소스를 지정한다.
• PATCH: 리소스의 부분 업데이트를 수행한다. 요청 분문은 리소스에 적용할 변경 내용을 지정한다.
• DELETE: 지정된 URI의 리소스를 제거한다.

특정 요청의 효과는 리소스가 컬렉션인지 아니면 개별 항목인지에 따라 달라진다. 다음 표는 전자 상거래 예제를 사용하여 대부분의 RESTful 구현에서 적용하는 일반적인 규칙을 요약한다. 이러한 요청 중 일부는 특정 시나리오에 따라 구현되지 않을 수 있다.

리소스	GET	POST	PUT	DELETE
/customers	모든 고객 검색	새 고객 만들기	고객 대량 업데이트	모든 고객 제거
/customers/1	고객 1에 대한 세부 정보 검색	Error	고객 1이 있는 경우 고객 1의 세부 정보 업데이트	고객 1 제거
/customers/1/orders	고객 1에 대한 모든 주문 검색	고객 1에 대한 새 주문 만들기	고객 1의 주문 대량 업데이트	고객 1의 모든 주문 제거

 

POST, PUT 및 PATCH의 차이점을 구분하기 어려울 수 있다.

• POST 요청은 리소스를 만든다. 서버는 새 리소스에 대한 URI를 할당하고 클라이언트에 해당 URI를 반환한다. REST 모델에서는 컬렉션에 POST 요청을 자주 적용한다. 새 리소스가 컬렉션에 추가된다. POST 요청은 새 리소스를 만들지 않고 기존 리소스에 처리할 데이터를 보내는데 사용할 수도 있다.
• PUT 요청은 리소스를 만들거나 기존 리소스를 업데이트한다. 클라이언트는 리소스의 URI를 지정한다. 요청 본문에는 리소스의 완전한 표현이 포함된다. 이 URI를 사용하는 리소스가 이미 있으면 리소스가 대체된다. 아직 없고 서버에서 리소스 만들기를 지원하는 경우 새 리소스가 생성된다. PUT 요청은 컬렉션보다는 특정 고객 같은 개별 항목인 리소스에 가장 자주 적용된다. 서버에서 PUT을 통한 업데이트를 지원하지만 만들기는 지원하지 않을 수 있다. PUT을 통한 만들기 지원 여부는 리소스가 존재하기 전에 클라이언트가 이미 있는 방법으로 리소스에 URI를 할당할 수 있는지 여부에 따라 결정된다. 할당할 수 없는 경우 POST를 사용하여 리소스를 만들고 PUT 또는 PATCH를 사용하여 업데이트한다.
• PATCH 요청은 기존 리소스에 부분 업데이트를 수행한다. 클라이언트는 리소스의 URI를 지정한다. 요청 본문은 리소스에 적용할 변경 내용을 지정한다. 클라이언트가 리소스의 전체 표현이 아닌 변경 내용만 보내기 때문에 PUT을 사용하는 것보다 이 방법이 더 효율적일 수 있다. 또한 서버에서 리소스 만들기를 지원하는 경우 기술적으로는 PATCH는 새 리소스를 만들 수 있다("null" 리소스에 대한 업데이트를 지정하여).

PUT 요청은 idempotent여야 한다. 클라이언트가 동일한 PUT 요청을 여러 번 제출하는 경우 그 결과가 항상 같아야 한다(같은 값을 사용하여 같은 리소스가 수정되므로). POST 및 PATCH 요청이 반드시 idempotent가 된다는 보장은 없다.

 

 

출처: https://learn.microsoft.com/ko-kr/azure/architecture/best-practices/api-design

웹 API 디자인 모범 사례 - Azure Architecture Center