Skip to content

Commit 083e8bf

Browse files
authored
feat(132): clarify operator precedence (#260)
It's unclear at this point what order the various AEPs should be applied on an API endpoint, if they exist. Adding a section to clarify this. An example of this precedence is drafted at aep-dev/aepc#60.
1 parent 60f1832 commit 083e8bf

File tree

1 file changed

+19
-10
lines changed

1 file changed

+19
-10
lines changed

aep/general/0132/aep.md.j2

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,25 @@ with an HTTP 404 error.
154154
**Note:** An empty collection which the user has permission to access **must**
155155
return `200 OK` with an empty results array, and not `404 Not Found`.
156156

157+
### Advanced operations
158+
159+
`List` methods **may** allow an extended set of functionality to allow a user to
160+
specify the resources that are returned in a response.
161+
162+
The following table summarizes the applicable AEPs, ordered by the precedence of
163+
the operation on the results.
164+
165+
| Operation | AEP |
166+
| ---------------------------- | --------------------------------- |
167+
| filter | [AEP-160](/160) |
168+
| ordering (`orderBy`) | [AEP-132](#ordering) |
169+
| pagination (`nextPageToken`) | [AEP-158](/158) |
170+
| skip | [AEP-158](/158/#skipping-results) |
171+
172+
For example, if both the `filter` and `skip` fields are specified, then the
173+
filter would be applied first, then the resulting set would be the results that
174+
skip N entries of the filtered result.
175+
157176
### Ordering
158177

159178
`List` methods **may** allow clients to specify sorting order; if they do, the
@@ -171,16 +190,6 @@ request message **should** contain a `string orderBy` field.
171190
**Note:** Only include ordering if there is an established need to do so. It is
172191
always possible to add ordering later, but removing it is a breaking change.
173192

174-
### Filtering
175-
176-
List methods **may** allow clients to specify filters; if they do, the request
177-
message **should** contain a `string filter` field. Filtering is described in
178-
more detail in AEP-160.
179-
180-
**Note:** Only include filtering if there is an established need to do so. It
181-
is always possible to add filtering later, but removing it is a breaking
182-
change.
183-
184193
### Soft-deleted resources
185194

186195
Some APIs need to "[soft-delete][]" resources, marking them as deleted or

0 commit comments

Comments
 (0)