Skip to content

Commit cb2a30a

Browse files
fix(133): add oas examples (#232)
Adding oas examples for create. This also tests out the pattern outlined in #230 - adding a generated oas.yaml and use selective elements from it as an example, which looks to work pretty well. There is a blocker on aep-dev/site-generator#43 to allow for support from a json-path like structure to target sub-elements, but this will at least allow for selective guidance to be easily added. --------- Co-authored-by: Richard Frankel <[email protected]>
1 parent 1c968b7 commit cb2a30a

File tree

5 files changed

+447
-117
lines changed

5 files changed

+447
-117
lines changed

aep/general/0133/aep.md.j2

+13-40
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@ Create methods are specified using the following pattern:
3131
**should** be the only variable in the URI path.
3232
- The collection identifier (`books` in the above example) **must** be a
3333
literal string.
34+
- Some resources take longer to be created than is reasonable for a regular API
35+
request. In this situation, the API **should** use a [long-running
36+
operation](/long-running-operations).
3437

3538
{% tab proto %}
3639

@@ -61,7 +64,7 @@ rpc CreateBook(CreateBookRequest) returns (Book) {
6164

6265
{% tab oas %}
6366

64-
**Note:** OAS guidance not yet written
67+
{% sample '../oas.yaml', '$.paths./publishers/{publisher}/books.post' %}
6568

6669
{% endtabs %}
6770

@@ -107,38 +110,9 @@ message CreateBookRequest {
107110

108111
{% tab oas %}
109112

110-
**Note:** OAS guidance not yet written
113+
{% sample '../oas.yaml', '$.paths./publishers/{publisher}/books.post.requestBody' %}
111114

112-
{% endtabs %}
113-
114-
### Long-running create
115-
116-
Some resources take longer to create a resource than is reasonable for a
117-
regular API request. In this situation, the API **should** use a long-running
118-
operation (AEP-151) instead:
119-
120-
- The response type **must** be set to the resource (what the return type would
121-
be if the RPC was not long-running).
122-
123-
{% tab proto %}
124-
125-
```proto
126-
rpc CreateBook(CreateBookRequest) returns (aep.api.Operation) {
127-
option (google.api.http) = {
128-
post: "/v1/{parent=publishers/*}/books"
129-
};
130-
option (aep.api.operation_info) = {
131-
response_type: "Book"
132-
metadata_type: "OperationMetadata"
133-
};
134-
}
135-
```
136-
137-
- Both the `response_type` and `metadata_type` fields **must** be specified.
138-
139-
{% tab oas %}
140-
141-
**Note:** OAS guidance not yet written
115+
- The request body **must** be the resource being created.
142116

143117
{% endtabs %}
144118

@@ -167,10 +141,6 @@ publishers/lacroix/books/les-miserables
167141
publishers/012345678-abcd-cdef/books/12341234-5678-abcd
168142
```
169143

170-
- The `id` field **must** exist on the request message, not the resource
171-
itself.
172-
- The field **may** be required or optional. If it is required, it **should**
173-
include the corresponding annotation.
174144
- The `path` field on the resource **must** be ignored.
175145
- The documentation **should** explain what the acceptable format is, and the
176146
format **should** follow the guidance for resource path formatting in
@@ -187,15 +157,18 @@ publishers/012345678-abcd-cdef/books/12341234-5678-abcd
187157
the RPC, with a value of `"parent,{resource},id"` if the resource being
188158
created is not a top-level resource, or with a value of `"{resource},id"` if
189159
the resource being created is a top-level resource.
160+
- The `id` field **must** exist on the request message, not the resource
161+
itself.
162+
- The field **may** be required or optional. If it is required, it **should**
163+
include the corresponding annotation.
190164

191165
{% tab oas %}
192166

193-
**Note:** OAS guidance not yet written
167+
{% sample '../oas.yaml', '$.paths./publishers/{publisher}/books.post.requestBody' %}
194168

195-
{% endtabs %}
169+
- The `id` field **must** be a query parameter on the request.
196170

197-
**Note:** For REST APIs, the user-specified ID field, `id`, is provided as a
198-
query parameters on the request URI.
171+
{% endtabs %}
199172

200173
### Errors
201174

aep/general/0134/aep.md.j2

+8-75
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,12 @@ Update methods are specified using the following pattern:
2424
- The response **should** include the fully-populated resource, and **must**
2525
include any fields that were sent and included in the update mask unless
2626
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.
3027
- The method **should** support partial resource update, and the HTTP verb
3128
**should** be `PATCH`.
3229
- 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).
3333

3434
{% tab proto %}
3535

@@ -54,7 +54,7 @@ rpc UpdateBook(UpdateBookRequest) returns (Book) {
5454

5555
{% tab oas %}
5656

57-
**Note:** OAS example not yet written.
57+
{% sample '../oas.yaml', '$.paths./publishers.post' %}
5858

5959
{% endtabs %}
6060

@@ -112,7 +112,7 @@ message UpdateBookRequest {
112112

113113
{% tab oas %}
114114

115-
**Note:** OAS example not yet written.
115+
{% sample '../oas.yaml', '$.paths./publishers.post.parameters' %}
116116

117117
{% endtabs %}
118118

@@ -160,79 +160,12 @@ If a rating were set on a book and the existing `PUT` request were executed, it
160160
would wipe out the book's rating. In essence, a `PUT` request unintentionally
161161
would wipe out data because the previous version did not know about it.
162162

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
194164

195165
If the service uses client-assigned resource paths, `Update` methods **may**
196166
expose a `bool allow_missing` field, which will cause the method to succeed in
197167
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).
236169

237170
{% tab proto %}
238171

@@ -312,7 +245,7 @@ message Book {
312245

313246
{% tab oas %}
314247

315-
**Note:** OAS example not yet written.
248+
{% sample '../oas.yaml', '$.components.schemas.publisher' %}
316249

317250
{% endtabs %}
318251

aep/general/0158/aep.md.j2

+1-1
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ message ListBooksResponse {
5555

5656
{% tab oas %}
5757

58-
**Note:** OAS example not yet written.
58+
{% sample '../oas.yaml', '$.paths./publishers.get' %}
5959

6060
{% endtabs %}
6161

aep/general/0217/aep.md.j2

+1-1
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ message ListBooksResponse {
3131

3232
{% tab oas %}
3333

34-
**Note:** OAS example note yet written.
34+
{% sample '../oas.yaml', '$.paths./publishers/{publisher}/books.get.responses.200.content.application/json' %}
3535

3636
{% endtabs %}
3737

0 commit comments

Comments
 (0)