From 370075d74daaa7c4941bb185bd1c5ced9ffff60b Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Mon, 1 Sep 2025 12:54:17 -0700 Subject: [PATCH] feat(122, oas): clarify parent field usage AEP-122 only has guidance on the parent path for proto. Adding OAS guidance to reduce confusion. Fixes #325 --- aep/general/0122/aep.md.j2 | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/aep/general/0122/aep.md.j2 b/aep/general/0122/aep.md.j2 index 5453c6c5..551e50b6 100644 --- a/aep/general/0122/aep.md.j2 +++ b/aep/general/0122/aep.md.j2 @@ -237,6 +237,8 @@ example: `file_path`). ### Fields representing a resource's parent +{% tab proto %} + When defining a method that retrieves resources from a collection or adds a new resource to a collection (such as `ListBooks` or `CreateBook`), the first field of the request message **should** be of type `string` and **should** be called @@ -281,6 +283,21 @@ string parent = 1 [ **Note:** Fields **should not** be called `parent` except for this purpose. For other use cases, use a synonymous term if possible. +{% tab oas %} + +For HTTP APIs, the parent is determined from the HTTP path of the resource. For +example, for the following book: + +``` +http://api.example.com/publishers/123/books/les-miserables +``` + +`publishers/123` is the parent resource. For any use cases in which the parent +is needed, they may be extracted from the HTTP path by removing the collection +and id suffix of the path (`books/les-miserables`) in the case above. + +{% endtabs %} + ### Fields representing another resource When referencing a resource path for a different resource, the field **should**