RFC 5789

PATCH Method for HTTP

📅 published March 2010, from ietf

RFC 5789: PATCH Method for HTTP 🎀

okay bestie, the title block first 💅 This is RFC 5789, called PATCH Method for HTTP, and it's a Standards Track doc from the IETF (ISSN 2070-1721). The authors are L. Dusseault from Linden Lab and J. Snell, and it was published in March 2010. The header doesn't list anything it obsoletes or updates, so there's no "replaces this old RFC" drama here 🧚

Abstract ✨

okay so apps that extend HTTP keep needing to change part of a resource, not the whole thing 🥺 the existing HTTP PUT method only does a complete replacement of a document, so that's a no-go for partial edits. this proposal adds a brand new HTTP method, PATCH, to modify an existing HTTP resource and fix that 🦋

Status of This Memo 📜

this is an Internet Standards Track document 🔥

it's a product of the Internet Engineering Task Force (IETF) and it represents the consensus of the IETF community. it got public review and was approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 5741 🌸

for the current status, any errata, and how to give feedback on it, go to http://www.rfc-editor.org/info/rfc5789 💜

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. all rights reserved 🫶

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents, which you can find at http://trustee.ietf.org/license-info (as in effect on the publication date). please actually read these, bestie, because they explain your rights and restrictions 🙈 and any Code Components pulled out of this doc must include the Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions. they come without warranty, as the Simplified BSD License describes 🍓

Table of Contents 📑

1. Introduction ....................................................2
2. The PATCH Method ................................................2
   2.1. A Simple PATCH Example .....................................4
   2.2. Error Handling .............................................5
3. Advertising Support in OPTIONS ..................................7
   3.1. The Accept-Patch Header ....................................7
   3.2. Example OPTIONS Request and Response .......................7
4. IANA Considerations .............................................8
   4.1. The Accept-Patch Response Header ...........................8
5. Security Considerations .........................................8
6. References ......................................................9
   6.1. Normative References .......................................9
   6.2. Informative References .....................................9
Appendix A.  Acknowledgements .....................................10

1. Introduction 💖

this spec defines the new HTTP/1.1 [RFC2616] method, PATCH, which is used to apply partial modifications to a resource. it's giving "finally" 😭

why do we even need a new method? a new method is necessary to improve interoperability and prevent errors 💅 PUT is already defined to overwrite a resource with a complete new body, so it can't be reused for partial changes. if we tried, proxies and caches, and even clients and servers, could get confused about what the operation actually did 🙈 POST is already used for this, but without broad interoperability. for one thing, there's no standard way to discover patch format support 💀 PATCH got mentioned in earlier HTTP specs, but it was never fully defined. so we're finishing that job 🧚

in this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC2119] 🌈

also, this doc uses the ABNF syntax defined in Section 2.1 of [RFC2616] 🎀

2. The PATCH Method 🦋

okay so the PATCH method asks that a set of changes, described in the request entity, be applied to the resource identified by the Request-URI 🔥 the set of changes is represented in a format called a "patch document", and that format is identified by a media type. and if the Request-URI doesn't point to an existing resource, the server MAY create a new resource. whether it can depends on the patch document type (like whether it can logically modify a null resource) and on permissions, etc. 👑

now the PUT vs PATCH difference is all about how the server handles the enclosed entity 💅 with a PUT, the enclosed entity is treated as a modified version of the resource stored on the origin server, and the client is asking for the stored version to be replaced. with PATCH, the enclosed entity is a set of instructions for how the resource currently on the origin server should be modified to produce a new version. the PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources. that means new resources may be created, or existing ones modified, by applying a PATCH 🧚

PATCH is neither safe nor idempotent as defined by [RFC2616], Section 9.1 😬

BUT you can send a PATCH request in a way that makes it idempotent, which also helps prevent bad outcomes from collisions between two PATCH requests on the same resource in a similar time frame 🫶 collisions from multiple PATCH requests can be more dangerous than PUT collisions, because some patch formats need to operate from a known base-point, or else they'll corrupt the resource 😭 so clients using this kind of patch application SHOULD use a conditional request, so the request fails if the resource has been updated since the client last accessed it. for example, the client can use a strong ETag [RFC2616] in an If-Match header on the PATCH request 🔒

there are also cases where patch formats don't need a known base-point, like appending text lines to log files or adding non-colliding rows to database tables 🍓 in those cases, the same care in client requests isn't needed. no stress 💅

the server MUST apply the entire set of changes atomically, and it must never provide a partially modified representation (for example, in response to a GET during this operation) ✨ if the entire patch document can't be successfully applied, the server MUST NOT apply any of the changes 🚫 what counts as a successful PATCH can vary depending on the patch document and the type of resource(s) being modified. for example, the common 'diff' utility can generate a patch document that applies to multiple files in a directory hierarchy. the atomicity requirement holds for all directly affected files 🌸 see "Error Handling", Section 2.2, for details on status codes and possible error conditions 🙈

if the request goes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale 🥀 a response to this method is only cacheable if it contains explicit freshness information (such as an Expires header or "Cache-Control: max-age" directive), and the Content-Location header matches the Request-URI, which shows that the PATCH response body is a resource representation. even then, a cached PATCH response can only be used to respond to subsequent GET and HEAD requests. it MUST NOT be used to respond to other methods (in particular, PATCH) 🚫

⚠️ bestie, read this part carefully: entity-headers in the request apply only to the contained patch document. they MUST NOT be applied to the resource being modified 💀

so a Content-Language header could be on the request, but it would only mean (for whatever that's worth) that the patch document had a language 😂 servers SHOULD NOT store such headers except as trace information, and SHOULD NOT use those header values the same way they might be used on PUT requests 🙅‍♀️ this doc doesn't specify a way to change a document's Content-Type or Content-Language through headers, though a mechanism could definitely be designed to do that through a patch document 🧚

there's no guarantee that a resource can be modified with PATCH 😔 different patch document formats are expected to suit different types of resources, and no single format will suit all of them. so there is no single default patch document format that implementations are required to support 🌈 and servers MUST ensure that a received patch document is appropriate for the type of resource identified by the Request-URI 👑

clients need to choose when to use PATCH instead of PUT 🤔 for example, if the patch document is larger than the size of the new resource data that would go in a PUT, it might make sense to use PUT instead 🍓 comparing to POST is even trickier, because POST gets used in widely varying ways and can cover PUT and PATCH-like operations if the server chooses. if the operation doesn't modify the resource identified by the Request-URI in a predictable way, POST should be considered instead of PATCH or PUT 💅

2.1. A Simple PATCH Example 🎀

here's the vibe. this is a request:

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

[description of changes]

this example shows a hypothetical patch document on an existing resource ✨

and here's a successful PATCH response to an existing text file 🦋

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

the 204 response code is used because the response doesn't carry a message body (which a 200 response would have) 🫶 other success codes could be used too, so don't panic if you see one 🌸

also, the ETag response header field has the ETag for the entity created by applying the PATCH. it's available at http://www.example.com/file.txt, as shown by the Content-Location response header field 💜

to be continued in part 2 🎀💖

2.2. Error Handling ✨

okay so PATCH requests can go wrong in a bunch of different ways, and the spec is literally giving us a little troubleshooting guide 💅 let's go through them bestie 🫶

Malformed patch document 🙈: if the server looks at the patch document and it's not formatted properly, it SHOULD send back a 400 (Bad Request) response. what counts as "badly formatted" totally depends on which patch document format you picked, so no single rule for everyone 🌸

Unsupported patch document 🎀: this one gets a 415 (Unsupported Media Type) response. it's for when the client sends a patch document format the server doesn't do for the resource at the Request-URI. the response SHOULD include an Accept-Patch response header (we'll get to that in Section 3.1) so the client can see which patch document media types ARE supported. very helpful, very iconic 👑

Unprocessable request 🔥: here we use a 422 (Unprocessable Entity) response ([RFC4918], Section 11.2). this is when the server understands the patch document and it looks syntactically valid, but the server still can't process it. like, attempting a change that would make the resource invalid. the example they give is a change to a well-formed XML document that would make it NOT well-formed anymore 💀 there might also be more specific errors, like "Conflicting State", that could go with this status code, but a more specific error is usually more helpful 🦋

Resource not found 🧚: a 404 (Not Found) status code can show up when the client tries to apply a patch to a resource that doesn't exist, but the patch document can't be applied to a nonexistent resource anyway 🌈

Conflicting state 💜: a 409 (Conflict) status code can be used when the request can't be applied because of the resource's current state. for example, if the client tried a structural change but the structures it assumed were there... aren't. (the XML example is that a patch says "change element 'foo' to element 'bar'" but 'foo' doesn't exist.) ngl that's a very relatable mess 😭

Conflicting modification ⭐: when the client uses If-Match or If-Unmodified-Since to set a precondition and that precondition fails, the 412 (Precondition Failed) error is the most helpful one for the client. BUT that response makes zero sense if there was no precondition on the request. so if the server spots a possible conflicting modification and no precondition was set, it can send back a 409 (Conflict) response 🍓

Concurrent modification 🌸: some PATCH applications need the server to handle requests in the order they arrive. if a server is working under those rules, gets concurrent requests to change the same resource, and can't queue them, it can use a 409 (Conflict) response to say so ✨

Note that a 409 Conflict response gives clients pretty consistent info 🫶 depending on the application and the patch format, the client might be able to just reissue the request as-is (like "append a line to a log file"), might have to GET the resource content and recalculate the patch, or might have to give up on the operation entirely 💖

Other HTTP status codes can also be used when the situation calls for them 🌈

And the entity body of error responses SHOULD contain enough info to tell the client what went wrong 🎀 the content-type of that response can vary across implementations, so no one format is required 💅

3. Advertising Support in OPTIONS 🦋

A server can advertise PATCH support by adding it to the list of allowed methods in the "Allow" OPTIONS response header (the one defined in HTTP/1.1) 🌸 PATCH MAY appear in the "Allow" header even if the Accept-Patch header is absent. in that case, though, the list of allowed patch documents just isn't advertised 🤷‍♀️

3.1. The Accept-Patch Header 💜

This spec introduces a brand-new response header called Accept-Patch 🎀 It's used to say which patch document formats the server accepts. Accept-Patch SHOULD appear in the OPTIONS response for any resource that supports PATCH 🔥

Here's the cool part: if Accept-Patch shows up in a response to ANY method, that's an implicit sign that PATCH is allowed on the resource at the Request-URI 👑 And if a specific patch document format is listed in it, that format is allowed on that resource too ✨

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

The Accept-Patch header is a comma-separated list of media-types (with optional parameters), as defined by [RFC2616], Section 3.7 🍓

Example:

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

3.2. Example OPTIONS Request and Response 🧚

[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

These examples show a server that supports PATCH in general, using two hypothetical patch document formats 🌈

4. IANA Considerations 🌸

4.1. The Accept-Patch Response Header ✨

The Accept-Patch response header has been added to the permanent registry (see [RFC3864]) 🎀

Header field name: Accept-Patch 🦋

Applicable Protocol: HTTP 💖

Author/Change controller: IETF 👑

Specification document: this specification 💅

5. Security Considerations 🔥

okay bestie, this part is SERIOUS 😭 the security considerations for PATCH are nearly identical to the ones for PUT ([RFC2616], Section 9.6) 💜 that includes authorizing requests (through access control and/or authentication) and making sure data doesn't get corrupted by transport errors or accidental overwrites 🫶 Whatever mechanisms you use for PUT can be used for PATCH too ✨ Then there are some extra considerations that apply especially to PATCH 🦋

A document that's been patched might be more likely to get corrupted than one that gets overwritten entirely 💀 but that worry can be handled with things like conditional requests using ETags and the If-Match request header, as described in Section 2 🌸 If a PATCH request fails, the client can send a GET request to the resource to see what state it's in 🎀 In some cases the client might be able to check the resource contents to see if the PATCH can be resent, but in other cases the attempt will just fail and/or a user will have to verify their intent 🙈 If the underlying transport channel fails, or some other timeout happens, before a PATCH response arrives, the client might have to GET the resource to see whether the request was applied 😭 The client might also want to make sure that GET bypasses caches, using mechanisms described in the HTTP specifications (see, for example, Section 13.1.6 of [RFC2616]) 🧚

Sometimes an HTTP intermediary tries to detect viruses by checking the body of PUT/POST requests or GET responses 🦠 PATCH makes that watch-keeping harder 🌈 because neither the source document nor the patch document might be a virus, but the result could still be one 💀 This isn't materially different from the concerns already raised by byte-range downloads, downloading patch documents, uploading zipped (compressed) files, and so on 💅

Individual patch documents will have their own security considerations, which will likely vary depending on the types of resources being patched 👑 For example, the considerations for patched binary resources will be different from those for patched XML documents 🍓

Servers MUST take adequate precautions to ensure that malicious clients cannot consume excessive server resources (e.g., CPU, disk I/O) through the client's use of PATCH 🔥🔥

6. References 💖

6.1. Normative References 🎀

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 🦋

[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, June 1999. 🌸

[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, September 2004. ✨

6.2. Informative References 🧚

[RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 🌈

Appendix A. Acknowledgements 💜

PATCH is not a new concept 🫶 it first appeared in HTTP in drafts of version 1.1 written by Roy Fielding and Henrik Frystyk, and it also appears in Section 19.6.1.1 of RFC 2068 ✨

Thanks to 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, and Bernie Hoeneisen for review and advice on this document 🎀 In particular, Julian Reschke did repeated reviews, made many useful suggestions, and was critical to the publication of this document 👑🔥

Authors' Addresses 🦋

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 💖

📦 where this page comes from