From 2c182eea384ce1c43a5e70c50867044bac03f0aa Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Sat, 14 Dec 2024 12:49:14 -0800 Subject: [PATCH] fix(standard-methods): clarify optional parent fields (#252) 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. --- aep/general/0132/aep.md.j2 | 12 ++++++------ aep/general/0133/aep.md.j2 | 21 ++++++++++----------- 2 files changed, 16 insertions(+), 17 deletions(-) diff --git a/aep/general/0132/aep.md.j2 b/aep/general/0132/aep.md.j2 index 6d760c1d..6d3d404d 100644 --- a/aep/general/0132/aep.md.j2 +++ b/aep/general/0132/aep.md.j2 @@ -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 a parent collection (if one exists), and return a +list of responses matching that input. ## Guidance @@ -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 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 %} diff --git a/aep/general/0133/aep.md.j2 b/aep/general/0133/aep.md.j2 index 84ed8efc..adaf9259 100644 --- a/aep/general/0133/aep.md.j2 +++ b/aep/general/0133/aep.md.j2 @@ -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 @@ -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 %} @@ -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**