Skip to content

Commit af11ea8

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 af11ea8

1 file changed

Lines changed: 32 additions & 0 deletions

File tree

aep/general/0122/aep.md.j2

Lines changed: 32 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,36 @@ 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+
301+
{% tab oas %}
302+
303+
For HTTP APIs, the parent is determined from the HTTP path of the resource. For
304+
example, for the following book:
305+
306+
```
307+
http://api.example.com/publishers/123/books/les-miserables
308+
```
309+
310+
`publishers/123` is the parent resource. For any use cases in which the parent
311+
is needed, they may be extracted from the HTTP path by removing the collection
312+
and id suffix of the path (`books/les-miserables`) in the case above.
313+
314+
{% endtabs %}
315+
284316
### Fields representing another resource
285317

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

0 commit comments

Comments
 (0)