@@ -24,12 +24,12 @@ Update methods are specified using the following pattern:
24
24
- The response **should** include the fully-populated resource, and **must**
25
25
include any fields that were sent and included in the update mask unless
26
26
they are input only (see AEP-203).
27
- - If the update RPC is [long-running](#long-running-update), the response
28
- **must** be an `Operation` for which the return type is the resource
29
- itself.
30
27
- The method **should** support partial resource update, and the HTTP verb
31
28
**should** be `PATCH`.
32
29
- The operation **must** have [strong consistency][].
30
+ - Some resources take longer to be created than is reasonable for a regular API
31
+ request. In this situation, the API should use a [long-running
32
+ operation](/long-running-operations).
33
33
34
34
{% tab proto %}
35
35
@@ -54,7 +54,7 @@ rpc UpdateBook(UpdateBookRequest) returns (Book) {
54
54
55
55
{% tab oas %}
56
56
57
- **Note:** OAS example not yet written.
57
+ {% sample '../oas.yaml' , '$.paths./publishers.post' %}
58
58
59
59
{% endtabs %}
60
60
@@ -112,7 +112,7 @@ message UpdateBookRequest {
112
112
113
113
{% tab oas %}
114
114
115
- **Note:** OAS example not yet written.
115
+ {% sample '../oas.yaml' , '$.paths./publishers.post.parameters' %}
116
116
117
117
{% endtabs %}
118
118
@@ -160,79 +160,12 @@ If a rating were set on a book and the existing `PUT` request were executed, it
160
160
would wipe out the book's rating. In essence, a `PUT` request unintentionally
161
161
would wipe out data because the previous version did not know about it.
162
162
163
- ### Long-running update
164
-
165
- Some resources take longer to update a resource than is reasonable for a
166
- regular API request. In this situation, the API **should** use a [long-running
167
- operation][AEP-151] instead:
168
-
169
- - The response type **must** be set to the resource (what the return type would
170
- be if the method were not long-running).
171
-
172
- {% tab proto %}
173
-
174
- ```proto
175
- rpc UpdateBook(UpdateBookRequest) returns (aep.api.Operation) {
176
- option (google.api.http) = {
177
- patch: "/v1/{book.name=publishers/*/books/*}"
178
- };
179
- option (aep.api.operation_info) = {
180
- response_type: "Book"
181
- metadata_type: "OperationMetadata"
182
- };
183
- }
184
- ```
185
-
186
- - Both the `response_type` and `metadata_type` fields **must** be specified.
187
-
188
- {% tab oas %}
189
-
190
- **Note:** OAS example not yet written.
191
-
192
- {% endtabs %}
193
-
163
+ ### Create or Update
194
164
195
165
If the service uses client-assigned resource paths, `Update` methods **may**
196
166
expose a `bool allow_missing` field, which will cause the method to succeed in
197
167
the event that the user attempts to update a resource that is not present (and
198
- will create the resource in the process):
199
-
200
- {% tab proto %}
201
-
202
- ```proto
203
- message UpdateBookRequest {
204
- ...
205
-
206
- // If set to true, and the book is not found, a new book will be created.
207
- // In this situation, `update_mask` is ignored.
208
- bool allow_missing = 3;
209
- }
210
- ```
211
-
212
- {% tab oas %}
213
-
214
- **Note:** OAS example not yet written.
215
-
216
- {% endtabs %}
217
-
218
- More specifically, the `allow_missing` flag triggers the following behavior:
219
-
220
- - If the method call is on a resource that does not exist, the resource is
221
- created. All fields are applied regardless of any provided field mask.
222
- - However, if any required fields are missing or fields have invalid values,
223
- an `INVALID_ARGUMENT` error is returned.
224
- - If the method call is on a resource that already exists, and all fields
225
- match, the existing resource is returned unchanged.
226
- - If the method call is on a resource that already exists, only fields declared
227
- in the field mask are updated.
228
-
229
- The user **must** have the update permissions to call `Update` even with
230
- `allow_missing` set to `true`.
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):
168
+ will create the resource in the process).
236
169
237
170
{% tab proto %}
238
171
@@ -312,7 +245,7 @@ message Book {
312
245
313
246
{% tab oas %}
314
247
315
- **Note:** OAS example not yet written.
248
+ {% sample '../oas.yaml' , '$.components.schemas.publisher' %}
316
249
317
250
{% endtabs %}
318
251
0 commit comments