인터넷 엔지니어링 태스크 포스(IETF)

L. Dusseault

Request for Comments: 5789

Linden Lab

카테고리: Standards Track

J. Snell

ISSN: 2070-1721

2010년 3월

HTTP용 PATCH 메서드

요약

하이퍼텍스트 전송 프로토콜(HTTP)을 확장하는 여러 애플리케이션은 부분적인 리소스 수정을 수행하는 기능을 필요로 합니다. 기존의 HTTP PUT 메서드는 문서의 전체 교체만 허용합니다. 본 제안은 기존의 HTTP 리소스를 수정하기 위해 PATCH라는 새로운 HTTP 메서드를 추가합니다.

이 메모의 상태

이 문서는 인터넷 표준 트랙 문서입니다.

이 문서는 인터넷 엔지니어링 태스크 포스(IETF)의 산물입니다. 이는 IETF 커뮤니티의 합의를 반영합니다. 공개 검토를 거쳤으며 인터넷 엔지니어링 운영 그룹(IESG)에 의해 출판 승인을 받았습니다. 인터넷 표준에 대한 추가 정보는 RFC 5741의 섹션 2에서 확인할 수 있습니다.

이 문서의 현재 상태, 정오표, 및 이에 대한 피드백 제공 방법에 관한 정보는 http://www.rfc-editor.org/info/rfc5789에서 확인할 수 있습니다.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

1. 소개
2. PATCH 메서드
- 2.1. 간단한 PATCH 예
- 2.2. 오류 처리
3. OPTIONS에서의 지원 광고
- 3.1. Accept-Patch 헤더
- 3.2. 예시 OPTIONS 요청 및 응답
4. IANA 고려사항
- 4.1. Accept-Patch 응답 헤더
5. 보안 고려사항
6. 참고문헌
- 6.1. 규범적 참조
- 6.2. 정보적 참조
Appendix A. 감사의 글
저자 주소

1. 소개

이 명세서는 리소스에 부분 수정을 적용하는 데 사용되는 새로운 HTTP/1.1 [RFC2616] 메서드인 PATCH를 정의합니다.

상호운용성을 개선하고 오류를 방지하기 위해 새로운 메서드가 필요합니다. PUT 메서드는 이미 문서를 전체 새 본문으로 덮어쓰도록 정의되어 있어 부분 변경에 재사용할 수 없습니다. 그렇지 않으면 프록시와 캐시, 심지어 클라이언트와 서버도 연산 결과에 대해 혼동할 수 있습니다. POST는 이미 사용되고 있지만 광범위한 상호운용성을 갖추고 있지 않습니다(예: 패치 형식 지원을 발견하는 표준화된 방법이 없음). PATCH는 이전 HTTP 명세에서 언급되었지만 완전하게 정의되지는 않았습니다.

이 문서에서 핵심 단어 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 및 "OPTIONAL"은 [RFC2119]에 설명된 대로 해석됩니다.

또한, 이 문서는 [RFC2616]의 섹션 2.1에 정의된 ABNF 문법을 사용합니다.

2. PATCH 메서드

PATCH 메서드는 요청 엔티티에 기술된 변경 집합을 Request-URI로 식별된 리소스에 적용하도록 요청합니다. 변경 집합은 미디어 타입으로 식별되는 "패치 문서"라고 불리는 형식으로 표현됩니다. Request-URI가 기존 리소스를 가리키지 않는 경우, 서버는 패치 문서 형식(널 리소스를 논리적으로 수정할 수 있는지 여부)과 권한 등에 따라 새 리소스를 생성할 수 있습니다(MAY).

PUT 요청과 PATCH 요청의 차이는 서버가 리소스를 수정하기 위해 포함된 엔티티를 처리하는 방식에서 반영됩니다. PUT 요청에서는 포함된 엔티티가 원점 서버에 저장된 리소스의 수정된 버전으로 간주되어, 클라이언트는 저장된 버전의 교체를 요청합니다. 반면 PATCH에서는 포함된 엔티티가 원점 서버에 현재 존재하는 리소스를 새로운 버전으로 만들기 위해 어떻게 수정해야 하는지를 설명하는 명령 집합을 포함합니다. PATCH 메서드는 Request-URI로 식별된 리소스에 영향을 주며, 또한 다른 리소스에 부작용을 가질 수도 있습니다; 즉, PATCH 적용으로 새 리소스가 생성되거나 기존 리소스가 수정될 수 있습니다.

PATCH는 [RFC2616] 섹션 9.1에서 정의된 바와 같이 안전도(safe)나 멱등(idempotent)이 아닙니다.

PATCH 요청은 멱등하게 발행될 수 있으며, 이는 유사한 시점에 동일한 리소스에 대한 두 개의 PATCH 요청이 충돌할 때 발생할 수 있는 좋지 않은 결과를 방지하는 데 도움이 됩니다. 여러 PATCH 요청으로 인한 충돌은 일부 패치 형식이 알려진 기준점(base-point)에서 동작해야 하거나 그렇지 않으면 리소스를 손상시킬 수 있기 때문에 PUT 충돌보다 더 위험할 수 있습니다. 이러한 패치 적용을 사용하는 클라이언트는 자원이 클라이언트가 마지막으로 접근한 이후 업데이트되었을 경우 요청이 실패하도록 하는 조건부 요청을 사용해야 합니다(SHOULD). 예를 들어, 클라이언트는 PATCH 요청에 If-Match 헤더에 강한 ETag를 사용할 수 있습니다.

로그 파일에 텍스트 라인을 추가하거나 데이터베이스 테이블에 충돌하지 않는 행을 추가하는 등 패치 형식이 알려진 기준점에서 동작할 필요가 없는 경우도 있으며, 이런 경우 클라이언트 요청에서 동일한 주의가 필요하지 않습니다.

서버는 전체 변경 집합을 원자적으로 적용해야 하며(예: 이 작업 도중 GET에 응답할 때) 부분적으로 수정된 표현을 제공해서는 안 됩니다. 패치 문서를 전체적으로 성공적으로 적용할 수 없는 경우, 서버는 어떤 변경도 적용해서는 안 됩니다. PATCH의 성공을 무엇으로 정의할지는 패치 문서와 수정되는 리소스 유형에 따라 달라질 수 있습니다. 예를 들어, 일반적인 'diff' 유틸리티는 디렉터리 계층의 여러 파일에 적용되는 패치 문서를 생성할 수 있습니다. 원자성 요구사항은 모든 직접 영향을 받는 파일에 대해 적용됩니다. 상태 코드 및 가능한 오류 조건에 대한 세부사항은 "오류 처리", 섹션 2.2를 참조하십시오.

요청이 캐시를 통과하고 Request-URI가 하나 이상의 현재 캐시된 엔터티를 식별하는 경우, 해당 엔트리는 오래된 것으로 취급되어야 합니다(SHOULD). 이 메서드에 대한 응답은 명시적 신선도 정보(예: Expires 헤더 또는 "Cache-Control: max-age" 지시자)와 함께 Content-Location 헤더가 Request-URI와 일치하여 PATCH 응답 본문이 리소스 표현임을 나타내는 경우에만 캐시 가능(cacheable)합니다. 캐시된 PATCH 응답은 이후의 GET 및 HEAD 요청에 응답하는 데만 사용될 수 있으며, 다른 메서드(특히 PATCH)에 응답하는 데는 사용되어서는 안 됩니다.

요청에 포함된 엔티티-헤더는 포함된 패치 문서에만 적용되며 수정되는 리소스에 적용되어서는 안 됩니다(MUST NOT). 따라서 요청에 Content-Language 헤더가 있을 수 있지만, 이는 패치 문서가 특정 언어를 가짐을 의미할 뿐입니다. 서버는 이러한 헤더를 추적 정보로만 저장해야 하며(SHOULD), PUT 요청에서 사용될 수 있는 방식으로 이러한 헤더 값을 사용해서는 안 됩니다. 따라서 이 문서는 헤더를 통해 문서의 Content-Type 또는 Content-Language 값을 수정하는 방법을 명시하지 않습니다. 다만 패치 문서를 통해 이 목표를 달성할 수 있는 메커니즘이 설계될 수 있습니다.

리소스를 PATCH로 수정할 수 있다는 보장은 없습니다. 또한 서로 다른 패치 문서 형식이 서로 다른 유형의 리소스에 적합할 것이고 단일 형식이 모든 리소스 유형에 적합하지 않을 것으로 예상됩니다. 따라서 구현체가 반드시 지원해야 하는 단일 기본 패치 문서 형식은 없습니다. 서버는 수신된 패치 문서가 Request-URI로 식별된 리소스 유형에 적합한지 확인해야 합니다(MUST).

클라이언트는 PATCH 대신 언제 PUT을 사용할지 선택해야 합니다. 예를 들어, 패치 문서의 크기가 PUT에 사용할 새 리소스 데이터의 크기보다 큰 경우에는 PATCH 대신 PUT을 사용하는 것이 더 적절할 수 있습니다. POST와의 비교는 더 어려운데, POST는 매우 다양한 방식으로 사용되며 서버가 선택하면 PUT 및 PATCH 유사 동작을 포함할 수 있기 때문입니다. 작업이 Request-URI로 식별된 리소스를 예측 가능한 방식으로 수정하지 않는 경우에는 PATCH나 PUT 대신 POST를 고려해야 합니다.

2.1. 간단한 PATCH 예

PATCH /file.txt HTTP/1.1
Host: www.example.com
Content-Type: application/example
If-Match: "e0023aa4e"
Content-Length: 100

[description of changes]

이 예시는 기존 리소스에 가상의 패치 문서를 사용하는 예를 보여줍니다.

기존 텍스트 파일에 대한 성공적인 PATCH 응답:

HTTP/1.1 204 No Content
Content-Location: /file.txt
ETag: "e0023aa4f"

응답이 메시지 본문을 포함하지 않으므로(200 응답과 달리) 204 응답 코드를 사용합니다. 다른 성공 코드도 사용할 수 있습니다.

또한 ETag 응답 헤더 필드는 Content-Location 응답 헤더 필드로 표시된 대로 http://www.example.com/file.txt에서 PATCH를 적용하여 생성된 엔티티의 ETag를 포함합니다.

2.2. 오류 처리

PATCH 요청이 실패할 수 있는 여러 알려진 조건이 있습니다.

잘못된 패치 문서 형식:: 서버가 클라이언트가 제공한 패치 문서가 올바르게 형식화되지 않았다고 판단하는 경우, 400 (Bad Request) 응답을 반환하는 것이 바람직합니다(SHOULD). 잘못된 형식의 정의는 선택된 패치 문서에 따라 다릅니다.
지원되지 않는 패치 문서:: 클라이언트가 서버가 Request-URI로 식별된 리소스에 대해 지원하지 않는 패치 문서 형식을 보낸 경우, 415 (Unsupported Media Type) 응답으로 지정할 수 있습니다. 이러한 응답에는 클라이언트에게 지원되는 패치 문서 미디어 타입을 알리기 위해 섹션 3.1에 설명된 Accept-Patch 응답 헤더를 포함하는 것이 바람직합니다(SHOULD).
처리 불가 요청:: 서버가 패치 문서를 이해하고 문서의 구문이 유효해 보이지만 요청을 처리할 수 없는 경우에는 422 (Unprocessable Entity) 응답([RFC4918] 섹션 11.2)으로 지정할 수 있습니다. 예를 들어, 잘 형성된 XML 문서를 더 이상 잘 형성되지 않게 만드는 수정을 시도하는 경우 등이 이에 해당합니다. 또한 "충돌 상태(Conflicting State)"와 같은 더 구체적인 오류가 이 상태 코드로 신호될 수 있지만, 보다 구체적인 오류가 일반적으로 더 유용합니다.
리소스 없음:: 클라이언트가 존재하지 않는 리소스에 패치 문서를 적용하려고 시도했으나 선택된 패치 문서가 존재하지 않는 리소스에 적용될 수 없는 경우 404 (Not Found) 상태 코드로 지정할 수 있습니다.
상태 충돌:: 요청이 리소스의 상태로 인해 적용될 수 없는 경우 409 (Conflict) 상태 코드로 지정할 수 있습니다. 예를 들어 클라이언트가 구조적 수정을 시도했는데 예상되는 구조가 존재하지 않는 경우(XML의 경우 'foo' 요소를 'bar'로 변경하라는 패치가 있지만 'foo' 요소가 존재하지 않을 수 있음)가 이에 해당합니다.
수정 충돌:: 클라이언트가 사전 조건을 정의하기 위해 If-Match 또는 If-Unmodified-Since 헤더를 사용했고 그 사전 조건이 실패한 경우, 412 (Precondition Failed)가 클라이언트에게 가장 유용합니다. 그러나 요청에 사전 조건이 없었다면 이 응답은 의미가 없습니다. 서버가 가능한 충돌 수정을 감지하고 요청에 사전 조건이 정의되지 않은 경우, 서버는 409 (Conflict) 응답을 반환할 수 있습니다.
동시 수정:: PATCH의 일부 적용은 서버가 요청을 수신된 순서대로 처리해야 할 수 있습니다. 서버가 이러한 제약 하에 운영되고 있고 동일 리소스를 수정하기 위한 동시 요청을 받았으나 해당 요청을 큐잉할 수 없는 경우, 서버는 409 (Conflict) 응답으로 이 오류를 나타낼 수 있습니다.

409 Conflict 응답은 클라이언트에게 비교적 일관된 정보를 제공합니다. 애플리케이션 및 패치 형식의 특성에 따라 클라이언트는 요청을 그대로 재전송할 수 있거나(예: 로그 파일에 라인을 추가하는 지시), 패치를 재계산하기 위해 리소스 콘텐츠를 다시 가져와야 하거나, 작업이 실패하여 사용자 확인이 필요할 수 있습니다.

적절한 상황에서는 다른 HTTP 상태 코드도 사용할 수 있습니다.

오류 응답의 엔티티 본문은 클라이언트에게 오류의 성격을 전달할 수 있을 만큼 충분한 정보를 포함하는 것이 바람직합니다(SHOULD). 응답 엔티티의 Content-Type은 구현마다 다를 수 있습니다.

3. OPTIONS에서의 지원 광고

서버는 HTTP/1.1에서 정의된 "Allow" OPTIONS 응답 헤더의 허용된 메서드 목록에 PATCH를 추가함으로써 PATCH 지원을 광고할 수 있습니다. Accept-Patch 헤더가 없더라도 PATCH 메서드는 "Allow" 헤더에 나타날 수 있으며, 이 경우 허용된 패치 문서 목록은 광고되지 않습니다.

3.1. Accept-Patch 헤더

이 명세서는 서버가 수용하는 패치 문서 형식을 지정하기 위해 사용되는 새로운 응답 헤더 Accept-Patch를 도입합니다. Accept-Patch는 PATCH 메서드 사용을 지원하는 모든 리소스의 OPTIONS 응답에 나타나는 것이 바람직합니다(SHOULD). 어떤 메서드에 대한 응답에서 Accept-Patch 헤더가 존재하면 이는 암묵적으로 Request-URI로 식별된 리소스에서 PATCH가 허용됨을 나타냅니다. 이 헤더에 특정 패치 문서 형식이 존재하면 해당 형식이 Request-URI로 식별된 리소스에서 허용된다는 것을 나타냅니다.

Accept-Patch = "Accept-Patch" ":" 1#media-type

Accept-Patch 헤더는 [RFC2616] 섹션 3.7에 정의된 대로 선택적 매개변수를 가진 쉼표로 구분된 미디어 타입 목록을 지정합니다.

예:

Accept-Patch: text/example;charset=utf-8

3.2. 예시 OPTIONS 요청 및 응답

[request]

OPTIONS /example/buddies.xml HTTP/1.1
Host: www.example.com

[response]

HTTP/1.1 200 OK
Allow: GET, PUT, POST, OPTIONS, HEAD, DELETE, PATCH
Accept-Patch: application/example, text/example

예시는 서버가 일반적으로 PATCH를 지원하며 두 가지 가상의 패치 문서 형식을 사용하는 것을 보여줍니다.

4. IANA 고려사항

4.1. Accept-Patch 응답 헤더

Accept-Patch 응답 헤더가 영구 레지스트리에 추가되었습니다(자세한 내용은 [RFC3864] 참조).

헤더 필드 이름:: Accept-Patch
적용 프로토콜:: HTTP
저자/변경 제어자:: IETF
명세 문서:: 본 명세서

5. 보안 고려사항

PATCH에 대한 보안 고려사항은 PUT에 대한 보안 고려사항([RFC2616] 섹션 9.6)과 거의 동일합니다. 여기에는 요청 권한 부여(액세스 제어나 인증을 통해) 및 전송 오류나 우발적 덮어쓰기를 통해 데이터가 손상되지 않도록 하는 것이 포함됩니다. PUT에 사용되는 모든 메커니즘은 PATCH에도 사용할 수 있습니다. 다음 고려사항들은 특히 PATCH에 적용됩니다.

패치된 문서는 전체를 덮어쓰는 문서보다 손상될 가능성이 더 높을 수 있지만, 이는 섹션 2에서 설명된 대로 ETag와 If-Match 요청 헤더를 사용하는 조건부 요청과 같은 메커니즘으로 해결할 수 있습니다. PATCH 요청이 실패하면 클라이언트는 리소스 상태를 확인하기 위해 GET 요청을 보낼 수 있습니다. 일부 경우 클라이언트는 PATCH 요청을 재전송할 수 있는지 확인하기 위해 리소스 내용을 검사할 수 있지만, 다른 경우에는 시도가 실패하고/또는 사용자가 의도를 확인해야 할 수 있습니다. 전송 채널의 실패로 인해 PATCH 응답이 채널 실패 또는 시간 초과 전에 수신되지 않은 경우, 클라이언트는 요청이 적용되었는지 확인하기 위해 GET 요청을 발행해야 할 수 있습니다. 클라이언트는 GET 요청이 캐시를 우회하도록 HTTP 명세에 설명된 메커니즘을 사용하도록 할 수 있습니다(예: [RFC2616] 섹션 13.1.6 참조).

때때로 HTTP 중개자는 PUT/POST 요청의 본문이나 GET 응답을 검사하여 전송되는 바이러스를 탐지하려고 할 수 있습니다. PATCH 메서드는 소스 문서나 패치 문서 자체가 바이러스가 아닐 수 있지만 결과가 바이러스일 수 있기 때문에 이러한 감시를 복잡하게 만듭니다. 이 보안 고려사항은 바이트 범위 다운로드, 패치 문서 다운로드, 압축된(zip) 파일 업로드 등 이미 도입된 것들과 실질적으로 다르지 않습니다.

개별 패치 문서는 패치되는 리소스 유형에 따라 달라지는 고유한 보안 고려사항을 가질 것입니다. 예를 들어, 바이너리 리소스를 패치하는 경우와 XML 문서를 패치하는 경우의 고려사항은 다릅니다. 서버는 악의적인 클라이언트가 PATCH를 통해 과도한 서버 자원(예: CPU, 디스크 I/O)을 소비하지 못하도록 적절한 예방 조치를 취해야 합니다(MUST).

6. 참고문헌

6.1. 규범적 참조

[RFC2119]: Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, 1997년 3월.
[RFC2616]: Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1”, RFC 2616, 1999년 6월.
[RFC3864]: Klyne, G., Nottingham, M., and J. Mogul, “Registration Procedures for Message Header Fields”, BCP 90, RFC 3864, 2004년 9월.

6.2. 정보적 참조

[RFC4918]: Dusseault, L., “HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)”, RFC 4918, 2007년 6월.

Appendix A. 감사의 글

PATCH는 새로운 개념이 아니며, 처음에는 Roy Fielding과 Henrik Frystyk가 작성한 HTTP 1.1 초안에 등장했으며 RFC 2068의 섹션 19.6.1.1에도 나타납니다.

Adam Roach, Chris Sharp, Julian Reschke, Geoff Clemm, Scott Lawrence, Jeffrey Mogul, Roy Fielding, Greg Stein, Jim Luther, Alex Rousskov, Jamie Lokier, Joe Hildebrand, Mark Nottingham, Michael Balloni, Cyrus Daboo, Brian Carpenter, John Klensin, Eliot Lear, SM, 및 Bernie Hoeneisen에게 이 문서의 검토 및 조언에 감사드립니다. 특히 Julian Reschke는 반복적인 검토와 많은 유용한 제안을 했으며, 이 문서의 출판에 중요한 역할을 했습니다.

저자 주소

Lisa Dusseault
Linden Lab
945 Battery Street
San Francisco, CA 94111
USA
Email: lisa.dusseault@gmail.com

James M. Snell
Email: jasnell@gmail.com
URI: http://www.snellspace.com