Skip to content

Commit 01c82ef

Browse files
authored
fix(132): should -> must on parent field (#318)
Some guidance includes "should" on parent fields. However, this is a requirement in order for AEP clients and users to understand the resource hierarchy. This is an artifact of the adaptation of the AEP from aip.dev, and currently there is not justification for the *should*.
1 parent 3784bfe commit 01c82ef

File tree

1 file changed

+8
-7
lines changed

1 file changed

+8
-7
lines changed

aep/general/0132/aep.md.j2

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,15 @@ result **must** be a list of resources.
2727
name **should** be the plural form of the resource's message name.
2828
- The request message **must** match the RPC name, with a `-Request` suffix.
2929
- The response message **must** match the RPC name, with a `-Response` suffix.
30-
- The response **should** usually include fully-populated resources unless
31-
there is a reason to return a partial response (see AEP-157).
30+
- The response **should** include fully-populated resources unless there is a
31+
reason to return a partial response (see AEP-157).
3232
- The HTTP verb **must** be `GET`.
33-
- If the collection has a parent resource, The URI **should** contain a field
33+
- If the collection has a parent resource, The URI **must** contain a field
3434
corresponding to the collection parent's name.
35-
- This field **should** be called `parent`.
36-
- The URI **should** have a variable corresponding to this field.
37-
- The `parent` field **should** be the only variable in the URI path. All
38-
remaining parameters **should** map to URI query parameters.
35+
- This field **must** be called `parent`.
36+
- The URI **must** have a variable corresponding to this field.
37+
- The `parent` field **must** be the only variable in the URI path. All
38+
remaining parameters **must** map to URI query parameters.
3939
- There **must not** be a `body` key in the `google.api.http` annotation.
4040
- There **should** be exactly one `google.api.method_signature` annotation with
4141
a value of `"parent"` if a parent exists, and an empty string otherwise.
@@ -78,6 +78,7 @@ collection's URI:
7878
- The field **must** be [annotated as required][aep-203].
7979
- The field **must** identify the [resource type][] of the resource being
8080
listed with a `google.api.resource_reference` annotation.
81+
- The field **must** accept the parent [path, _not_ the id](./0122)
8182
- The `max_page_size` and `page_token` fields, which support pagination,
8283
**must** be specified on all list request messages. For more information, see
8384
AEP-158.

0 commit comments

Comments
 (0)