Skip to content

Commit 370075d

Browse files
committed
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
1 parent fb52306 commit 370075d

File tree

1 file changed

+17
-0
lines changed

1 file changed

+17
-0
lines changed

aep/general/0122/aep.md.j2

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,8 @@ example: `file_path`).
237237

238238
### Fields representing a resource's parent
239239

240+
{% tab proto %}
241+
240242
When defining a method that retrieves resources from a collection or adds a new
241243
resource to a collection (such as `ListBooks` or `CreateBook`), the first field
242244
of the request message **should** be of type `string` and **should** be called
@@ -281,6 +283,21 @@ string parent = 1 [
281283
**Note:** Fields **should not** be called `parent` except for this purpose. For
282284
other use cases, use a synonymous term if possible.
283285

286+
{% tab oas %}
287+
288+
For HTTP APIs, the parent is determined from the HTTP path of the resource. For
289+
example, for the following book:
290+
291+
```
292+
http://api.example.com/publishers/123/books/les-miserables
293+
```
294+
295+
`publishers/123` is the parent resource. For any use cases in which the parent
296+
is needed, they may be extracted from the HTTP path by removing the collection
297+
and id suffix of the path (`books/les-miserables`) in the case above.
298+
299+
{% endtabs %}
300+
284301
### Fields representing another resource
285302

286303
When referencing a resource path for a different resource, the field **should**

0 commit comments

Comments
 (0)