HTTP 메서드: PUT

웹 애플리케이션과 RESTful API 설계에서 PUT 메서드는 리소스의 생성 및 갱신(업데이트) 을 담당하는 중요한 HTTP 메서드 중 하나입니다.
PUT 메서드는 특정 URI(Uniform Resource Identifier)에 위치한 자원을 완전히 대체하거나, 존재하지 않을 경우 새롭게 생성하는 역할을 합니다.

이번 글에서는 PUT 메서드의 개념, 특징, 실제 활용 사례, 그리고 다른 HTTP 메서드와의 차이점을 깊이 있게 살펴보겠습니다.

---

1. PUT 메서드란?

PUT 메서드는 서버의 특정 자원을 생성하거나 기존 데이터를 새로운 값으로 대체하는 HTTP 요청 방식입니다.
이는 클라이언트가 특정 위치에 있는 자원을 명확하게 정의하고, 그 자원을 새로운 상태로 교체할 때 사용됩니다.

📌 PUT 요청의 기본 형식:

PUT /resource/123 HTTP/1.1
Host: www.example.com
Content-Type: application/json
Content-Length: 82

• /resource/123 → 업데이트할 자원의 고유한 URI.
• Content-Type: application/json → JSON 데이터를 전송.
• 요청 본문(Body)에 수정할 데이터 포함.

💡 PUT 메서드의 핵심 개념:

• 서버의 특정 리소스를 갱신(Update)하거나, 존재하지 않으면 새로 생성(Create).
• 완전한 대체(Full Replacement) → 기존 데이터가 새로운 데이터로 완전히 덮어씌워짐.
• 멱등성(Idempotency) 보장 → 동일한 요청을 여러 번 보내도 서버 상태는 동일하게 유지.

---

2. PUT 메서드의 주요 특징

1️⃣ 자원(리소스)의 생성 및 갱신

PUT 요청을 보내면 서버는 해당 URI의 리소스를 업데이트하거나, 존재하지 않으면 새로 생성합니다.
이 과정에서 기존 리소스가 완전히 새로운 데이터로 교체되므로, 부분 업데이트가 아닌 전체 업데이트를 수행하는 것이 특징입니다.

📌 예제 (사용자 정보 업데이트 – REST API 활용)

PUT /users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "홍길동",
  "email": "hong@example.com",
  "age": 30
}

• 서버는 ID가 123인 사용자의 기존 데이터를 완전히 덮어씌움.
• 기존 데이터에 "phone": "010-1234-5678" 속성이 있었다면, 해당 속성이 삭제되고 위의 새로운 데이터만 저장됨.
• 부분 업데이트(필드 일부 수정)가 필요한 경우 PATCH 메서드를 사용해야 함.

💡 중요한 점:

• PUT은 기존 데이터를 완전히 대체하는 방식이므로, 누락된 데이터는 삭제될 수 있음.
• 특정 필드만 업데이트하려면 PATCH 메서드를 고려해야 함.

---

2️⃣ 멱등성(Idempotency) 보장

📌 PUT 요청은 멱등(Idempotent)한 요청 방식

• 동일한 PUT 요청을 여러 번 반복해도 서버의 상태가 변하지 않음.
• 같은 데이터를 PUT 요청으로 계속 보내더라도, 최종 결과는 동일해야 함.

📌 비교 예제 (PUT vs. POST – 멱등성 차이)

요청 방식	설명	멱등성 여부
PUT /users/123	ID가 123인 사용자 정보를 업데이트	✅ 멱등 (같은 요청 반복 시 동일한 결과)
POST /users	새로운 사용자 생성	❌ 멱등 아님 (여러 번 호출하면 중복 데이터 생성 가능)

💡 PUT을 여러 번 실행해도 결과가 동일하게 유지되므로, 신뢰성이 필요한 데이터 처리에 적합함.

---

3️⃣ 응답 상태 코드(Status Code)와 동작 방식

PUT 요청의 응답은 상태 코드를 통해 처리 결과를 전달합니다.

• 200 OK → 기존 리소스가 정상적으로 업데이트됨.
• 201 Created → 리소스가 존재하지 않아 새롭게 생성됨.
• 204 No Content → 요청은 성공했으나, 응답 본문이 없음.

📌 예제 (PUT 요청 후 응답 메시지 – 성공적인 업데이트)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "홍길동",
  "email": "hong@example.com",
  "age": 30
}

• 기존 데이터가 업데이트되었으므로 200 OK 반환.
• 수정된 데이터를 응답 본문에 포함하여 반환.

📌 예제 (새로운 리소스 생성 – 201 Created 응답)

HTTP/1.1 201 Created
Location: /users/123
Content-Length: 0

• 기존 데이터가 없어서 새로운 사용자가 생성됨.
• Location 헤더를 통해 생성된 리소스의 위치(URL)를 제공.

---

3. PUT 요청의 실제 활용 예시

1️⃣ 사용자 정보 업데이트

PUT /users/456 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "김철수",
  "email": "chulsoo@example.com"
}

• ID가 456인 사용자의 정보를 수정.
• 기존 데이터가 "phone": "010-5678-1234"을 포함하고 있었다면, 이 필드는 삭제될 수 있음.

---

2️⃣ 제품 정보 업데이트

PUT /products/789 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "노트북",
  "price": 1500000,
  "stock": 10
}

• 제품 정보가 완전히 교체되므로, 기존 속성이 삭제되지 않도록 모든 값을 포함해야 함.

---

4. PUT vs. 다른 HTTP 메서드 비교

메서드	목적	멱등성	요청 본문 포함	캐싱 가능 여부
GET	데이터 조회	✅	❌	✅
POST	새로운 데이터 생성	❌	✅	❌
PUT	기존 데이터 수정/대체	✅	✅	❌
PATCH	기존 데이터 일부 수정	❌	✅	❌
DELETE	데이터 삭제	✅	❌	❌

💡 PUT은 POST와 다르게 기존 데이터를 덮어씌우는 방식이며, 멱등성을 보장.
💡 PUT과 PATCH의 차이점은 전체 교체 vs. 부분 업데이트.

---

5. 결론

🔹 PUT 메서드는 특정 URI에 위치한 리소스를 갱신하거나, 존재하지 않으면 새롭게 생성하는 HTTP 메서드입니다.
🔹 멱등성을 보장하여 여러 번 동일한 요청을 보내도 결과가 변하지 않으며, RESTful API에서 데이터 일관성을 유지하는 데 유용합니다.
🔹 전체 데이터를 덮어씌우므로, 기존 데이터가 유지되어야 한다면 모든 필드를 포함해야 합니다.
🔹 POST(새 리소스 생성) 및 PATCH(부분 수정)와의 차이를 명확히 이해하고 적절한 상황에서 사용해야 합니다. 🚀

PUT 메서드를 올바르게 이해하고 활용하면 효율적인 API 설계와 안정적인 데이터 처리가 가능합니다!