Skip to content

Commit 39e5180

Browse files
mkistlerrofrankeltoumorokoshi
authored
feat(231): adopt batch Get (#177)
Importing batch-get from aip.dev. --------- Co-authored-by: Richard Frankel <[email protected]> Co-authored-by: Yusuke Tsutsumi <[email protected]>
1 parent 2257780 commit 39e5180

File tree

3 files changed

+250
-5
lines changed

3 files changed

+250
-5
lines changed

‎aep/general/0231/aep.md.j2

+177-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,179 @@
11
# Batch methods: Get
22

3-
**Note:** This AEP has not yet been adopted. See
4-
[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/42) for more
5-
information.
3+
Some APIs need to allow users to get a specific set of resources at a
4+
consistent time point (e.g. using a read transaction). A batch get method
5+
provides this functionality.
6+
7+
## Guidance
8+
9+
APIs **may** support batch get to retrieve a consistent set of resources.
10+
11+
- The method's name **must** begin with `BatchGet`. The remainder of the method
12+
name **must** be the plural form of the resource being retrieved.
13+
- The HTTP verb **must** be `GET`.
14+
- The HTTP URI **must** end with `:batchGet`.
15+
- The URI path **must** represent the collection for the resource, matching the
16+
collection used for simple CRUD operations. If the operation spans parents, a
17+
[wilcard](./reading-across-collections) **may** be accepted.
18+
- There **must not** be a request body.
19+
- If a GET request contains a body, the body **must** be ignored, and **must
20+
not** cause an error.
21+
22+
### Request
23+
24+
The request for a batch get method **should** be specified with the following
25+
pattern:
26+
27+
- The request **must** include an array field which accepts the resource paths
28+
specifying the resources to retrieve. The field **must** be named `paths`.
29+
- If no resource paths are provided, the API **should** error with
30+
`INVALID_ARGUMENT`.
31+
- The parameter **must** be required.
32+
- The documentation for the parameter **should** include the
33+
[resource type](./paths) that it references.
34+
- The parameter should define the pattern of the resource path values.
35+
- The parameter should define the maximum number of paths allowed.
36+
- Batch Get **should not** support pagination because transactionality across
37+
API calls would be extremely difficult to implement or enforce, and the
38+
request defines the exact scope of the response anyway.
39+
- The request **must not** contain any other required parameters, and **should
40+
not** contain other optional parameters except those described in this or
41+
another AEP.
42+
43+
{% tab proto -%}
44+
45+
```proto
46+
rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) {
47+
option (google.api.http) = {
48+
get: "/v1/{parent=publishers/*}/books:batchGet"
49+
};
50+
}
51+
52+
message BatchGetBooksRequest {
53+
// The parent resource shared by all books being retrieved.
54+
// Format: publishers/{publisher}
55+
// If this is set, the parent of all of the books specified in `paths`
56+
// must match this field.
57+
string parent = 1 [
58+
(google.api.resource_reference) = {
59+
child_type: "library.com/Book"
60+
}];
61+
62+
// The paths of the books to retrieve.
63+
// A maximum of 1000 books can be retrieved in a batch.
64+
// Format: publishers/{publisher}/books/{book}
65+
repeated string paths = 2 [
66+
(google.api.field_behavior) = REQUIRED,
67+
(google.api.resource_reference) = {
68+
type: "library.com/Book"
69+
}];
70+
}
71+
```
72+
73+
- The request schema **must** match the method name, with `Request` suffix.
74+
- A `parent` field **should** be included, unless the resource being retrieved
75+
is a top-level resource, to facilitate inclusion in the URI as well to permit
76+
a single permissions check. If a caller sets this field, and the parent
77+
collection in the path of any resource being retrieved does not match, the
78+
request **must** fail.
79+
- This field **should** be required if only 1 parent per request is allowed.
80+
- The field **should** identify the [resource type][aep-122-parent] that it
81+
references.
82+
- The comment for the field **should** document the resource pattern.
83+
- There **must not** be a body key in the `google.api.http` annotation.
84+
85+
{% tab oas %}
86+
87+
{% sample 'batchget.oas.yaml', 'paths' %}
88+
89+
- The `paths` parameter **must** be a query parameter which accepts an array of
90+
resource paths specifying the resources to retrieve.
91+
- If no resource paths are provided, the API **should** error with status
92+
code `400 Bad Request`.
93+
- If the collection in the path of any resource does not match the collection
94+
of the request URL, the request **must** fail.
95+
- The method definition **must not** have a `requestBody` defined.
96+
97+
{% endtabs %}
98+
99+
### Response
100+
101+
The response for a batch get method **must** be specified with the following
102+
pattern:
103+
104+
- The response schema **must** match the method name, with `Response` suffix.
105+
- The response schema **must** have a single array property where each item is
106+
either a retrieved resource or an error structure describing an error that
107+
occurred attempting to retrieve the resource. The error alternative would
108+
only be present for non-transactional batch gets.
109+
- The order of resources/error objects in the response **must** be the same as
110+
the paths in the request.
111+
- The array of resources **must** be named `results` and contain resources with
112+
no additional wrapping.
113+
- There **must not** be a `nextPageToken` field as batch get operations are not
114+
pageable.
115+
116+
{% tab proto -%}
117+
118+
```proto
119+
message BatchGetBooksResponse {
120+
// Books requested.
121+
repeated Book books = 1;
122+
}
123+
```
124+
125+
{% tab oas %}
126+
127+
{% sample 'batchget.oas.yaml', '/publishers/{publisherId}/books:BatchGet' %}
128+
129+
Example response body:
130+
131+
```json
132+
{
133+
"results": [
134+
{
135+
"name": "publishers/lacroix/books/les-mis",
136+
"isbn": "978-037-540317-0",
137+
"title": "Les Misérables",
138+
"authors": ["Victor Hugo"],
139+
"rating": 9.6
140+
},
141+
{
142+
"type": "https://datatracker.ietf.org/doc/html/rfc9110#name-404-not-found",
143+
"title": "The resource is not available"
144+
}
145+
{
146+
"name": "publishers/lacroix/books/hunchback-of-notre-dame",
147+
"isbn": "978-140-274575-1",
148+
"title": "The Hunchback of Notre Dame",
149+
"authors": ["Victor Hugo"],
150+
"rating": 9.3
151+
}
152+
]
153+
}
154+
```
155+
156+
{% endtabs %}
157+
158+
### Support for transactional get
159+
160+
The batch get method may support a transactional form of operation where the
161+
get either succeeds for all requested resources or fails. When supported, the
162+
method must define a boolean parameter `transactional` that the user must
163+
specify with the value `true` to request a transactional operation.
164+
165+
## Changelog
166+
167+
- **2024-04-22:** Adopt from Google AIP https://google.aip.dev/231 with the
168+
following changes:
169+
- Dropped the "nested requests" pattern.
170+
- Changed the response schema to an object with `results` array property.
171+
- Made transactional operation optional and controlled by asTransaction
172+
parameter.
173+
174+
<!-- Links -->
175+
176+
[aep-122-paths]: ./0122.md#fields-representing-resource-paths
177+
[aep-122-parent]: ./0122.md#fields-representing-a-resources-parent
178+
[aep-132]: https://aep.dev/132
179+
[get-request]: ./0131.md#get-request

‎aep/general/0231/aep.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
id: 231
3-
state: reviewing
3+
state: approved
44
slug: batch-get
5-
created: 2023-01-22
5+
created: 2024-04-22
66
placement:
77
category: batch-methods

‎aep/general/0231/batchget.oas.yaml

+71
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
openapi: 3.0.3
2+
info:
3+
title: Library
4+
version: 1.0.0
5+
paths:
6+
/publishers/{publisherId}/books:BatchGet:
7+
parameters:
8+
- name: publisherId
9+
in: path
10+
required: true
11+
schema:
12+
type: string
13+
get:
14+
operationId: BatchGetBooks
15+
description: Get multiple books in a batch.
16+
parameters:
17+
- name: paths
18+
in: query
19+
required: true
20+
description: >-
21+
The paths of the books to retrieve. Format:
22+
publishers/{publisherId}/books/{book}
23+
schema:
24+
type: array
25+
minItems: 1
26+
maxItems: 1000
27+
items:
28+
type: string
29+
responses:
30+
'200':
31+
description: OK
32+
content:
33+
application/json:
34+
schema:
35+
type: object
36+
properties:
37+
results:
38+
type: array
39+
items:
40+
oneOf:
41+
- $ref: '#/components/schemas/Book'
42+
- $ref: '#/components/schemas/Error'
43+
components:
44+
schemas:
45+
Book:
46+
description: A representation of a single book.
47+
type: object
48+
properties:
49+
name:
50+
type: string
51+
description: |
52+
The name of the book.
53+
Format: publishers/{publisher}/books/{book}
54+
isbn:
55+
type: string
56+
description: |
57+
The ISBN (International Standard Book Number) for this book.
58+
title:
59+
type: string
60+
description: The title of the book.
61+
authors:
62+
type: array
63+
items:
64+
type: string
65+
description: The author or authors of the book.
66+
rating:
67+
type: number
68+
format: float
69+
description: The rating assigned to the book.
70+
Error:
71+
type: object

0 commit comments

Comments
 (0)