1---
2category: documentation
3---
4
5# Patch Feature
6The HTTP PATCH method allows a resource to be partially updated.
7
8If a binding is mapped to patch and the request message has exactly one
9FieldMask message in it, additional code is rendered for the gateway
10handler that will populate the FieldMask based on the request body.
11
12There are two scenarios:
13- The FieldMask is hidden from the REST request as per the
14 [Google API design guide](https://cloud.google.com/apis/design/standard_methods#update)
15 (as in the first additional binding in the
16 [UpdateV2](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto#L366)
17 example).
18 In this case, the FieldMask is updated from the request body and
19 set in the gRPC request message.
20- The FieldMask is exposed to the REST request (as in the second
21 additional binding in the
22 [UpdateV2](https://github.com/grpc-ecosystem/grpc-gateway/blob/master/examples/internal/proto/examplepb/a_bit_of_everything.proto#L370)
23 example).
24 For this case, the field mask is left untouched by the gateway.
25
26## Example Usage
271. Create PATCH request.
28
29 The PATCH request needs to include the message and the update mask.
30 ```protobuf
31 // UpdateV2Request request for update includes the message and the update mask
32 message UpdateV2Request {
33 ABitOfEverything abe = 1;
34 google.protobuf.FieldMask update_mask = 2;
35 }
36 ```
372. Define your service in gRPC
38
39 If you want to use PATCH with fieldmask hidden from REST request only include the request message in the body.
40
41 ```protobuf
42 rpc UpdateV2(UpdateV2Request) returns (google.protobuf.Empty) {
43 option (google.api.http) = {
44 put: "/v2/example/a_bit_of_everything/{abe.uuid}"
45 body: "abe"
46 additional_bindings {
47 patch: "/v2/example/a_bit_of_everything/{abe.uuid}"
48 body: "abe"
49 }
50 };
51 }
52 ```
53
54 If you want to use PATCH with fieldmask exposed to the REST request then include the entire request message.
55
56 ```protobuf
57 rpc UpdateV2(UpdateV2Request) returns (google.protobuf.Empty) {
58 option (google.api.http) = {
59 patch: "/v2a/example/a_bit_of_everything/{abe.uuid}"
60 body: "*"
61 };
62 }
63 ```
64
653. Generate gRPC and reverse-proxy stubs and implement your service.
66
67## Curl examples
68
69In the example below we will partially update our ABitOfEverything
70resource by passing only the field we want to change. Since we are
71using the endpoint with field mask hidden we only need to pass the
72field we want to change ("string_value") and it will keep everything
73else in our resource the same.
74```shell
75$ curl \
76 --data '{"string_value": "strprefix/foo"}' \
77 -X PATCH \
78 http://address:port/v2/example/a_bit_of_everything/1
79```
80
81If we know what fields we want to update then we can use PATCH with
82field mask approach. For this we need to pass the resource and the
83update_mask. Below only the "single_nested" will get updated because
84that is what we specify in the field_mask.
85```shell
86$ curl \
87 --data '{"abe":{"single_nested":{"amount":457},"string_value":"some value that won't get updated because not in the field mask"},"update_mask":{"paths":["single_nested"]}}' \
88 -X PATCH \
89 http://address:port/v2a/example/a_bit_of_everything/1
90```
View as plain text