What is PATCH?
The HTTP method PUT means resource creation or replacement at some given URL.
Think files, for example. If you upload a file to S3 at some URL, you want either to create the file at that URL or replace an existing file if there’s one. That is PUT.
Now let’s say a web application has an
Invoice model with a
paid flag that
indicates whether the invoice has been paid. How do you set that flag in a
RESTful way? Submitting
paid=1 via PUT to
/invoices/:id does not conform to
HTTP semantics, because such request would not be sending a complete representation of the invoice for replacement.
With the constraints of the methods GET, POST, PUT, DELETE, the traditional answer
is to define the paid flag of a given invoice to be a resource by itself. So,
you define a route to be able to PUT
/invoices/:id/paid. You have
to do that because PUT does not allow partial updates to a resource.
Now let’s think about ordinary edit forms in typical Ruby on Rails applications.
How many times are we sending a complete representation for replacement? Not
always, perhaps we could say that it is even rare in practice that you do so.
For example, the conventional
updated_at timestamps normally
can’t be set by end-users, though they are often considered to belong to the
representation of resources that map to records.
PUT in addition is an idempotent method. You should be able to replay a request as many times as you want and get the same resource, something that sometimes is violated by conventional idioms for creating children resources using nested attributes while updating a parent resource.
There’s nothing theoretical preventing PUT from doing partial updates, but when HTTP was being standarized the replacement semantics were already deployed.
Because of that, the PATCH method was defined in 1995 and standarized later. PATCH is a method that is not safe, nor idempotent, and allows full and partial updates and side-effects on other resources.
In practice, as you see, PATCH suits everyday web programming way better than
PUT for updating resources. In Ruby on Rails it corresponds naturally to the way
update_attributes for updating records.
Thus, PATCH is going to be the primary method for updates in Rails 4.0.
This is an important change, but we plan to do it in a way that is backwards compatible.
When a resource is declared in config/routes.rb, for example,
the action in
UsersController to update a user is still
update in Rails 4.0.
PUT requests to
/users/:id in Rails 4.0 get routed to
update as they are
today. So, if you have an API that gets real PUT requests it is going to work.
In Rails 4.0, though, the router also routes PATCH requests to
So, in Rails 4.0 both PUT and PATCH are routed to
Forms of persisted resources:
get “patch” in the hidden field “_method”. The RFC is deliberately vague about the way to represent changes in a PATCH request. Submitting a form is perfectly valid, client and server must simply agree on the accepted ways to update a resource.
Let me emphasize that the “_method” hack is a workaround for the limitations in web browsers. As you probably know Rails routes real HTTP methods. That is, actual PUT, DELETE, and now, PATCH requests are routed to their respective actions.
PATCH requests are available in all places where the rest of the methods are
available today. There is a
patch macro for the routes DSL,
:patch. Tests can issue PATCH requests, request objects respond to
patch?, etc. Please see the original commit for details (with an important
Will my web server understand PATCH?
Yes, it should. I have personally tried Apache, nginx, Phusion Passenger, Unicorn, Thin, and WEBrick. They all understood PATCH requests out of the box.
Also, HTTP clients should be in general able to issue PATCH requests. For example in curl(1) you’d execute:
curl -d'user[name]=wadus' -X PATCH http://localhost:3000/users/1
Also I would like to highlight the quality of the patch itself. It is excellent: code, tests, all docs revised, comments in code revised. Everything carefully and thoroughly updated. An exemplar patch.