@@ -29,6 +29,7 @@ Update methods are specified using the following pattern:
29
29
itself.
30
30
- The method **should** support partial resource update, and the HTTP verb
31
31
**should** be `PATCH`.
32
+ - The operation **must** have [strong consistency][].
32
33
33
34
{% tab proto %}
34
35
@@ -190,7 +191,6 @@ rpc UpdateBook(UpdateBookRequest) returns (aep.api.Operation) {
190
191
191
192
{% endtabs %}
192
193
193
- ### Create or update
194
194
195
195
If the service uses client-assigned resource paths, `Update` methods **may**
196
196
expose a `bool allow_missing` field, which will cause the method to succeed in
@@ -229,6 +229,50 @@ More specifically, the `allow_missing` flag triggers the following behavior:
229
229
The user **must** have the update permissions to call `Update` even with
230
230
`allow_missing` set to `true`.
231
231
232
+ If the service uses client-assigned resource paths, `Update` methods **may**
233
+ expose a `bool allow_missing` field, which will cause the method to succeed in
234
+ the event that the user attempts to update a resource that is not present (and
235
+ will create the resource in the process):
236
+
237
+ {% tab proto %}
238
+
239
+ ```proto
240
+ message UpdateBookRequest {
241
+ // The book to update.
242
+ //
243
+ // The book's `path` field is used to identify the book to be updated.
244
+ // Format: publishers/{publisher}/books/{book}
245
+ Book book = 1 [(google.api.field_behavior) = REQUIRED];
246
+
247
+ // The list of fields to be updated.
248
+ google.protobuf.FieldMask update_mask = 2;
249
+
250
+ // If set to true, and the book is not found, a new book will be created.
251
+ // In this situation, `update_mask` is ignored.
252
+ bool allow_missing = 3;
253
+ }
254
+ ```
255
+
256
+ {% tab oas %}
257
+
258
+ **Note:** OAS example not yet written.
259
+
260
+ {% endtabs %}
261
+
262
+ More specifically, the `allow_missing` flag triggers the following behavior:
263
+
264
+ - If the method call is on a resource that does not exist, the resource is
265
+ created. All fields are applied regardless of any provided field mask.
266
+ - However, if any required fields are missing or fields have invalid values,
267
+ an `INVALID_ARGUMENT` error is returned.
268
+ - If the method call is on a resource that already exists, and all fields
269
+ match, the existing resource is returned unchanged.
270
+ - If the method call is on a resource that already exists, only fields declared
271
+ in the field mask are updated.
272
+
273
+ The user **must** have the update permissions to call `Update` even with
274
+ `allow_missing` set to `true`.
275
+
232
276
### Etags
233
277
234
278
An API may sometimes need to allow users to send update requests which are
@@ -312,7 +356,6 @@ unless `allow_missing` is set to `true`.
312
356
[aep-203]: ./0203.md
313
357
[create]: ./0133.md
314
358
[errors]: ./0193.md
315
- [management plane]: ./0111.md#management-plane
316
359
[permission-denied]: ./0193.md#permission-denied
317
360
[state fields]: ./0216.md
318
361
[strong consistency]: ./0121.md#strong-consistency
0 commit comments