잘 설계된 API에서 PUT과 PATCH는 서버의 리소스를 업데이트하는 데 사용되는 두 가지 HTTP 메서드입니다. REST API에서 PUT vs PATCH의 차이는 업데이트를 수행하는 방식과 각각이 적합한 상황에 있습니다. 두 메서드 모두 기존 데이터를 수정하기 위해 설계되었지만, REST API에서 PUT과 PATCH의 차이를 이해하면 개발자가 업데이트 성격에 따라 올바른 선택을 내릴 수 있습니다. 이 글에서는 REST API에서 PUT과 PATCH의 차이를 살펴보고, PATCH vs 업데이트 REST 논쟁, 각각의 사용 시점, 그리고 다양한 사용 사례에 맞는 메서드 선택 방법을 안내합니다.
REST API에서 PUT이란 무엇인가요?
REST API에서 PUT vs PATCH의 차이를 이해하려면 먼저 PUT이 무엇인지 알아야 합니다. 다음을 참고하면 섹션 9.6 RFC 2616, REST API에서 PUT 메서드는 요청 본문에 포함된 엔터티를 지정된 Request-URI에 저장하도록 요청합니다.
Request-URI가 이미 존재하는 리소스를 가리키는 경우, 포함된 엔터티는 원본 서버에 있는 리소스의 수정된 버전으로 처리되어야 합니다(SHOULD). Request-URI가 기존 리소스를 가리키지 않고, 요청을 보낸 사용자 에이전트가 해당 URI로 새 리소스를 정의할 수 있는 경우, 원본 서버는 해당 URI로 리소스를 생성할 수 있습니다.
즉, PUT 메서드는 서버의 리소스 전체를 업데이트할 때 사용합니다. 리소스를 완전히 교체해야 할 때 주로 쓰이는 만큼, PUT은 보다 '완전한' 업데이트 방식입니다.
PUT이 적합한 사용 사례는 다음과 같습니다:
- 리소스 전체를 업데이트할 때 (예: 사용자 프로필의 모든 정보를 새 데이터로 교체하는 경우).
- 항목이나 레코드 전체를 교체할 때.
- 리소스의 식별자가 명확하고, 데이터를 전부 새로 갱신해야 할 때.
I'd be happy to help translate to Korean, but the phrase "In systems like" appears incomplete. Could you please provide the full text you'd like me to translate? Elasticsearch, 데이터 일관성을 보장하려면 멱등성이 있는 작업이 필요합니다. 예를 들어, Elasticsearch의 문서를 PUT으로 업데이트하면 동일한 요청을 반복해도 의도치 않은 부작용이 발생하지 않습니다.
REST API에서 PATCH란 무엇인가요?
REST API에서 PUT을 살펴봤으니, 이제 PATCH가 무엇인지 알아보겠습니다. PUT vs PATCH를 비교하기 전에 REST API에서 PATCH가 어떻게 동작하는지 먼저 확인해 보겠습니다. 정의에 따르면, RFC 5789, REST API에서 PATCH 메서드는 요청 엔터티에 기술된 변경 사항을 Request-URI로 식별된 리소스에 적용하도록 요청합니다.
이것이 바로 PUT vs PATCH의 핵심 차이입니다. PATCH는 수정이 필요한 데이터만 전송하고, 서버는 리소스 전체를 바꾸지 않고 해당 변경 사항만 적용합니다. 개발자들은 이러한 부분 변경을 패치로 표현하는 경우가 많으며, 이를 통해 데이터 전송량을 최소화하고 효율적으로 업데이트할 수 있습니다.
따라서 REST API에서 PATCH 메서드는 다음 사용 사례에 더 적합합니다:
- 리소스의 일부 필드만 업데이트할 때 (예: 사용자의 이메일 주소나 전화번호 변경). PATCH API 예시로, 새 이메일만 전송하고 나머지 필드는 그대로 유지하는 경우를 들 수 있습니다.
- 전송 데이터를 줄여 성능을 높이고 싶을 때.
- 리소스 전체를 교체하지 않고 점진적으로 업데이트하고 싶을 때.
- 관련 없는 데이터에 영향을 주지 않고, 사용자 이메일 수정처럼 특정 필드 변경만 패치로 캡슐화할 때.
다음과 같은 플랫폼의 경우, 헤드리스 CMS 복잡한 콘텐츠 구조를 다루는 경우가 많기 때문에, 단일 필드 수정처럼 소규모 업데이트에는 PATCH를 사용하면 서버 부하를 줄이고 성능을 높일 수 있습니다.
지금까지 두 가지 메서드를 살펴봤으니, REST API에서 PUT과 PATCH가 무엇인지 어느 정도 파악했을 것입니다. 그런데 REST API에서 PUT vs PATCH의 차이를 본격적으로 다루기 전에, 두 메서드의 멱등성(Idempotence)에 대해 짚어볼 필요가 있습니다.
REST API에서 PUT vs PATCH의 멱등성
REST API에서 멱등성이란, 동일한 입력으로 작업을 여러 번 반복해도 결과가 항상 같은 성질을 말합니다. 즉, 동일한 요청을 몇 번 보내든 서버에 미치는 영향은 같아야 합니다. 이는 API의 안정성과 예측 가능성을 확보하는 데 중요합니다. 그렇다면 이것이 REST API에서 PUT과 PATCH의 차이와 어떤 관련이 있을까요?
PUT 메서드와 멱등성
REST API에서 PUT 메서드는 항상 멱등성을 가집니다. 지정된 URI의 리소스 전체를 요청에 포함된 데이터로 교체하도록 설계되어 있기 때문입니다. 즉, 동일한 리소스 데이터로 PUT 요청을 여러 번 보내도 결과는 항상 동일합니다.
PUT이 멱등성을 갖는 이유는 무엇일까요? PUT 요청을 보낸다는 것은 서버에 '이 리소스의 완전하고 정확한 상태는 이것입니다'라고 명시하는 것과 같습니다. PUT 요청을 한 번 보내든 여러 번 보내든, 최종 리소스 상태는 항상 동일합니다.
예를 들어, 사용자의 이메일 주소를 업데이트하는 경우를 생각해 보겠습니다. 동일한 PUT 요청을 여러 번 보내도 리소스는 매번 동일한 데이터로 교체되기 때문에 결과는 달라지지 않습니다.
예시:
| PUT /users/1{"username": "john_doe","email": "[email protected]"} |
이 요청을 여러 번 보내도 결과는 항상 동일합니다:
| {"username": "john_doe","email": "[email protected]"} |
사용자 데이터가 이미 동일한 상태라도, 같은 요청을 다시 보내도 결과는 달라지지 않습니다. 동일한 데이터로 교체하는 것이기 때문에, 요청을 몇 번 반복하든 결과는 항상 같습니다. PUT이 멱등성을 갖는 이유가 바로 이것입니다.
PATCH 메서드와 멱등성
반면 REST API의 PATCH 메서드도 일반적으로 멱등성을 가지지만, 더 유연하게 동작합니다. 패치를 만들 때는 반복 요청으로 인한 의도치 않은 부작용을 막기 위해 각 연산이 멱등성을 갖도록 설계해야 합니다(예: 값을 지정하는 방식). PATCH의 멱등성 여부는 연산의 종류와 수정 대상 데이터에 따라 달라집니다.
PATCH는 왜 멱등성을 가질까요? PATCH 요청에서 멱등성이란, 동일한 패치를 여러 번 적용해도 결과가 같다는 의미입니다. 패치를 반복 적용했을 때 추가적인 부작용이나 변경이 발생하지 않는 한, 이 조건은 유지됩니다. 동일한 데이터로 같은 패치를 계속 적용하면, 첫 번째 적용 이후 결과는 변하지 않아야 합니다.
예를 들어, 사용자의 이메일만 변경하는 경우 동일한 PATCH 요청을 여러 번 보내도 첫 번째 이후로는 결과가 달라지지 않습니다. 사용자의 이메일은 그대로 유지되고, 리소스 상태도 변하지 않습니다.
PATCH API 예시:
| PATCH /users/1{"email": "[email protected]"} |
이메일이 이미 [email protected]이었다면, 이 PATCH를 다시 적용해도 아무것도 바뀌지 않습니다. 멱등성이 성립하는 것입니다.
단, PATCH가 멱등성을 갖지 않는 경우도 있습니다. 예를 들어 카운터를 증가시키거나 배열에 항목을 추가하는 것처럼 상태를 누적하는 연산에서는, 동일한 PATCH를 반복 적용할 때마다 결과가 달라질 수 있습니다. 이 경우 멱등성 조건을 위반하게 됩니다.
멱등성이 없는 API REST PATCH 예시:
| PATCH /counter/1{"increment": 1} |
이 PATCH를 반복 적용하면 카운터가 계속 증가해 매번 다른 값이 나옵니다. 적용할 때마다 결과가 달라지므로 멱등성이 없습니다.
기본 개념을 파악했으니, 이제 실제 시나리오를 통해 REST API에서 PUT과 PATCH의 차이를 살펴보겠습니다.
예시 시나리오: REST API에서 PUT vs PATCH
이론은 여기까지입니다. 이제 멱등성이 있는 연산과 없는 연산을 포함한 예시를 통해 PUT과 PATCH의 차이를 직접 확인해 보겠습니다.
시나리오 1: PUT 요청 - 리소스 전체 교체
이커머스 시스템에서 상품을 관리하는 API 엔드포인트가 있다고 가정합니다. 상품의 이름, 가격, 설명 등 모든 정보를 업데이트해야 할 때, 전체 리소스를 교체하는 PUT을 사용하는 것이 전형적인 PUT vs PATCH의 HTTP 사용 사례입니다.
초기 상품
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
상품의 가격과 설명을 변경하려면, 전체 리소스를 담아 PUT 요청을 보냅니다.
PUT 요청:
| PUT /products/1001{"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
이 PUT 요청을 한 번 보내든 여러 번 보내든 결과는 항상 같습니다. 상품 정보는 새로운 가격과 설명으로 업데이트되며, 매번 동일한 결과가 보장됩니다. PUT의 멱등성이 보장되는 것입니다.
결과 (PUT 요청 후):
| {"id": 1001,"name": "Laptop","price": 899.99,"description": "A discounted powerful laptop."} |
시나리오 2: PATCH 요청 - 리소스 일부 업데이트
이번에는 상품 설명만 변경하는 PATCH 요청을 살펴봅니다. PATCH API 예시: 가격은 그대로 두고 상품 설명만 바꾸려면 PATCH가 더 적합한 선택입니다. 이 API REST PATCH 예시처럼, 수정이 필요한 필드만 담은 패치를 만들어 적용하면 됩니다.
초기 상품
| GET /products/1001{"id": 1001,"name": "Laptop","price": 999.99,"description": "A powerful laptop."} |
PATCH 요청:
| PATCH /products/1001{"description": "A lightweight, powerful laptop."} |
이 PATCH 요청을 보내면 description 필드만 업데이트됩니다. 동일한 PATCH 요청을 여러 번 보내도 첫 번째 업데이트 이후 description은 변경되지 않으므로, 이 요청은 멱등성을 가집니다.
결과 (PATCH 요청 후):
| {"id": 1001,"name": "Laptop","price": 999.99,"description": "A lightweight, powerful laptop."} |
동일한 PATCH를 다시 적용해도 상품 description은 첫 번째 PATCH 이후와 동일하게 유지됩니다. 결과가 일관되기 때문에 이 시나리오에서 PATCH는 멱등성을 가집니다.
시나리오 3: PATCH 요청 - 비멱등 연산
비멱등 PATCH 연산을 살펴보겠습니다. 사용자의 지갑 잔액을 다루는 엔드포인트가 있고 잔액을 증가시키려는 경우를 가정해 봅시다. PUT과 PATCH의 차이를 여기서 확인할 수 있는데, PATCH는 요청할 때마다 잔액에 값을 추가합니다.
초기 지갑:
| GET /users/1/wallet{"id": 1,"balance": 100.00} |
PATCH 요청:
| PATCH /users/1/wallet{"increment": 50.00} |
이 PATCH 요청은 지갑 잔액을 $50 증가시킵니다. 동일한 PATCH 요청을 여러 번 보내면 PATCH를 보낼 때마다 잔액이 계속 증가하여 매번 다른 결과가 나옵니다. 동일한 PATCH를 반복 적용할 때마다 결과가 달라지므로 이는 비멱등입니다.
결과 (첫 번째 PATCH 요청 후):
| {"id": 1,"balance": 150.00} |
결과 (두 번째 PATCH 요청 후):
| {"id": 1,"balance": 200.00} |
여기서 PATCH는 멱등성을 가지지 않습니다. 동일한 데이터로 요청을 반복해도 매번 다른 결과가 나오기 때문입니다.
요약: REST API에서 PUT vs PATCH의 주요 차이점
PUT과 PATCH의 핵심 차이는 REST API에서 업데이트를 처리하는 방식에 있습니다. PUT은 리소스 전체를 교체하므로 누락된 필드는 모두 삭제됩니다. 이는 데이터 손실로 이어질 수 있습니다. 그래서 개발자들은 변경되지 않은 필드를 덮어쓰지 않고 데이터 무결성을 유지하기 위해 부분 업데이트에 PATCH를 사용합니다.
이 점에서 PATCH는 부분 업데이트에 더 효율적입니다. API에서 PATCH를 활용하는 대표적인 예로, 사용자의 이메일만 업데이트하려는 경우 PATCH는 이메일 필드만 전송합니다. 반면 PUT 요청은 사용자 데이터 전체를 보내야 합니다.
PUT을 사용할 때는 전체 데이터 페이로드가 필요합니다. 모든 필드를 전송해야 하며, 누락된 필드는 삭제됩니다. 반면 PATCH는 업데이트가 필요한 필드만 전송하므로, 변경 사항이 적은 대용량 리소스에서 특히 효율적입니다. REST API의 PATCH 메서드는 더 집중적이고 작은 요청을 가능하게 하여 데이터 전송량을 줄여줍니다.
PUT과 PATCH는 모두 멱등성을 가집니다. 동일한 요청을 반복해도 결과가 같다는 의미입니다. 단, PUT은 리소스 전체를 교체하므로 결과가 더 예측 가능합니다. PATCH는 지정된 필드만 수정하지만, 서버에서 업데이트를 처리하는 방식에 따라 결과가 달라질 수 있습니다.
예를 들어 PATCH가 카운터를 증가시키는 경우, 요청을 반복하면 결과가 달라질 수 있습니다. 그럼에도 불구하고 API의 PATCH 연산은 멱등성을 가지도록 설계할 수 있습니다.
결론적으로, REST API에서 PUT과 PATCH의 차이는 업데이트의 성격에 달려 있습니다. PATCH는 부분 변경에, PUT은 리소스 전체 교체에 사용합니다. 둘 다 멱등성을 가지지만, PATCH는 더 복잡할 수 있습니다.
마치며
PUT과 PATCH는 REST API 설계의 핵심 HTTP 메서드이지만 용도가 다르며, 이것이 REST API에서 두 메서드의 본질적인 차이입니다. 이 글에서 살펴본 예제를 통해 PUT과 PATCH의 차이를 이해하면 API의 효율성, 명확성, 기능을 크게 향상시킬 수 있습니다. 사용 사례에 맞는 메서드(PATCH 대 REST 업데이트)를 선택하면 API를 더 효율적이고 유지보수하기 쉬우며 사용자 친화적으로 만들 수 있습니다. 업데이트가 전체인지 부분인지, 그리고 성능과 데이터 무결성에 미치는 영향을 항상 고려하여 요구사항에 가장 적합한 메서드를 선택하세요.
