From 5e26e7bfc2114ddf18a73cf59590816651ae4db0 Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Fri, 10 Jan 2025 09:44:21 -0800 Subject: [PATCH] feat(132): clarify operator precedence 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 https://github.com/aep-dev/aepc/pull/60. --- aep/general/0132/aep.md.j2 | 29 +++++++++++++++++++---------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/aep/general/0132/aep.md.j2 b/aep/general/0132/aep.md.j2 index 6d3d404d..4f9f1653 100644 --- a/aep/general/0132/aep.md.j2 +++ b/aep/general/0132/aep.md.j2 @@ -154,6 +154,25 @@ with an HTTP 404 error. **Note:** An empty collection which the user has permission to access **must** return `200 OK` with an empty results array, and not `404 Not Found`. +### Advanced operations + +`List` methods **may** allow an extended set of functionality to allow a user to +specify the resources that are returned in a response. + +The following table summarizes the applicable AEPs, ordered by the precedence of +the operation on the results. + +| Operation | AEP | +| ---------------------------- | --------------------------------- | +| filter | [AEP-160](/160) | +| ordering (`orderBy`) | [AEP-132](#ordering) | +| pagination (`nextPageToken`) | [AEP-158](/158) | +| skip | [AEP-158](/158/#skipping-results) | + +For example, if both the `filter` and `skip` fields are specified, then the +filter would be applied first, then the resulting set would be the results that +skip N entries of the filtered result. + ### Ordering `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. **Note:** Only include ordering if there is an established need to do so. It is always possible to add ordering later, but removing it is a breaking change. -### Filtering - -List methods **may** allow clients to specify filters; if they do, the request -message **should** contain a `string filter` field. Filtering is described in -more detail in AEP-160. - -**Note:** Only include filtering if there is an established need to do so. It -is always possible to add filtering later, but removing it is a breaking -change. - ### Soft-deleted resources Some APIs need to "[soft-delete][]" resources, marking them as deleted or