Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(standard-methods): clarify optional parent fields #252

Merged
merged 3 commits into from
Dec 14, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
toumorokoshi marked this conversation as resolved.
Show resolved Hide resolved
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.
toumorokoshi marked this conversation as resolved.
Show resolved Hide resolved
- 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
Loading