Skip to content

Commit

Permalink
fix(standard-methods): clarify optional parent fields
Browse files Browse the repository at this point in the history
There is currently some inconsistency with the description of
parent fields on standard methods, and whether they are required.

Clarifying that they are indeed optional, as the resource may
not have a parent.
  • Loading branch information
toumorokoshi committed Dec 12, 2024
1 parent c70e65a commit 1956706
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 17 deletions.
12 changes: 6 additions & 6 deletions aep/general/0132/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ collection's URI (for example, `/publishers/{publisher}/books`) in order to
retrieve a list of the resources within that collection.

Resource-oriented design (AEP-121) honors this pattern through the `List`
method. These RPCs accept the parent collection (and potentially some other
parameters), and return a list of responses matching that input.
method. These RPCs accept the a parent collection (if one exists), and and
return a list of responses matching that input.

## Guidance

Expand All @@ -30,15 +30,15 @@ result **must** be a list of resources.
- The response **should** usually include fully-populated resources unless
there is a reason to return a partial response (see AEP-157).
- The HTTP verb **must** be `GET`.
- The URI **should** contain a single variable field corresponding to the
collection parent's name.
- If the collection has a parent resource, The URI **should** contain a single
variable field corresponding to the collection parent's name.
- This field **should** be called `parent`.
- The URI **should** have a variable corresponding to this field.
- The `parent` field **should** be the only variable in the URI path. All
remaining parameters **should** map to URI query parameters.
- There **must not** be a `body` key in the `google.api.http` annotation.
- There **should** be exactly one `google.api.method_signature` annotation,
with a value of `"parent"`.
- There **should** be exactly one `google.api.method_signature` annotation with
a value of `"parent"` if a parent exists, and an empty string otherwise.

{% tab oas %}

Expand Down
21 changes: 10 additions & 11 deletions aep/general/0133/aep.md.j2
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@ In REST APIs, it is customary to make a `POST` request to a collection's URI
resource within that collection.

Resource-oriented design (AEP-121) honors this pattern through the `Create`
method. These RPCs accept the parent collection and the resource to create (and
potentially some other parameters), and return the created resource.
method. These RPCs accept the parent collection if one exists, and the resource
to create (and potentially some other parameters), and return the created
resource.

## Guidance

Expand All @@ -30,16 +31,13 @@ Create methods are specified using the following pattern:
- The RPC's name **must** begin with the word `Create`. The remainder of the
RPC name **should** be the singular form of the resource being created.
- The request message **must** match the RPC name, with a `Request` suffix.
- The collection's parent resource **must** be called `parent`, and
**should** be the only variable in the URI path.
- If the collection has a parent, the collection's parent resource **must** be
called `parent`, and **should** be the only variable in the URI path.
- The collection identifier (`books` in the above example) **must** be a
literal string.
- There **must** be a `body` key in the `google.api.http` annotation, and it
**must** map to the resource field in the request message.
- All remaining fields **should** map to URI query parameters.
- There **should** be exactly one `google.api.method_signature` annotation,
with a value of `"parent,{resource},id"`, or "`"parent,{resource}"` if the
resource ID is not required.
- The operation **must** have [strong consistency][].

{% tab oas %}
Expand Down Expand Up @@ -144,10 +142,11 @@ publishers/012345678-abcd-cdef/books/12341234-5678-abcd

{% tab proto %}

- There **should** be exactly one `google.api.method_signature` annotation on
the RPC, with a value of `"parent,{resource},id"` if the resource being
created is not a top-level resource, or with a value of `"{resource},id"` if
the resource being created is a top-level resource.
- There **should** be exactly one `google.api.method_signature` annotation, with
a comma-delimited list of values, including the field representing the
resource.
- If the collection has a parent, the list must include `parent`.
- If the resource supports user-settable ids, the list must include `id`.
- The `id` field **must** exist on the request message, not the resource
itself.
- The field **may** be required or optional. If it is required, it **should**
Expand Down

0 comments on commit 1956706

Please sign in to comment.