Skip to content

Commit 19fb876

Browse files
author
Luke Sneeringer
committed
Incorporate consensus feedback.
1 parent 8b58693 commit 19fb876

File tree

1 file changed

+33
-3
lines changed

1 file changed

+33
-3
lines changed

aip/general/0159/aip.md

Lines changed: 33 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,39 @@ what collection it is in.
66

77
## Guidance
88

9-
APIs **may** support reading resources across multiple collections by allowing
10-
users to specify a `-` (the hyphen or dash character) as a wildcard character
11-
in a standard [`List`][aip-132] operation:
9+
There are two potential approaches for reading resources across multiple
10+
collections. Groups of related services **should**, as a unit, select a
11+
preferred approach and apply it consistently.
12+
13+
### Promoting Resources
14+
15+
One approach is to evade the problem entirely by promoting resources above
16+
their erstwhile parents in the event that reading across collections is likely
17+
to be a requirement.
18+
19+
In this approach, the parent becomes a field on the resource:
20+
21+
```typescript
22+
interface Book {
23+
// The ID of the book's publisher
24+
publisherId: string;
25+
26+
// Other fields...
27+
}
28+
```
29+
30+
Similarly, the parent is removed from the URI:
31+
32+
```
33+
GET /v1/books?filter...
34+
```
35+
36+
### Wildcards
37+
38+
The other approach is to use a wildcard character. Services **may** support
39+
reading resources across multiple collections by allowing users to specify a
40+
`-` (the hyphen or dash character) as a wildcard character in a standard
41+
[`List`][aip-132] operation:
1242

1343
```
1444
GET /v1/publishers/-/books?filter=...

0 commit comments

Comments
 (0)