AIP-193: Clarify whether NOT_FOUND should be returned by the List method when there are no matching resources

[gkf]

I am guessing the intent is that when no resources match a List request, an empty result should be returned and not a NOT_FOUND error? So NOT_FOUND should only be returned when the parent resource does not exist? The wording is less clear after the reorganization in 88d2d62 since it now refers to "the requested resource or parent" instead of "the requested parent resource". The child resources returned by List could be considered to be "requested resources".

[andy-h-2016]

Can we get this question resolved? The wording of AIP-193 is ambiguous.

[noahdietz]

Sure thing, we can take a look.

I am guessing the intent is that when no resources match a List request, an empty result should be returned and not a NOT_FOUND error

Yes. Furthermore it is valid to return an empty set with a page_token as per AIP-158:

The API may return fewer results than the number requested (including zero results), even if not at the end of the collection.

So NOT_FOUND should only be returned when the parent resource does not exist?...since it now refers to "the requested resource or parent" instead of "the requested parent resource".

For the List case (and other collection-based methods), I think the correct interpretation here is "when the parent does not exist, return a NOT_FOUND" (including the permissions caveat of course). Put differently, the resources returned by a List are not "requested" because they were not targeted explicitly by a name field in the request payload. Yes, this is perhaps a subtle difference.

I'm not sure that the resolution to this bug lies in updating AIP-193, rather it probably makes more sense in AIP-158 or AIP-132. AIP-193 is not meant to be a definitive table of "X case, use Y code or behavior". That should reside with the specific design pattern discussed i.e. Pagination or Standard List. The Permission Denied section, if I'm honest, probably doesn't belong in AIP-193 which is more about how APIs should structure errors and what can be in them.

That said, would anyone like to open a PR to suggest a clarification to AIP-193 Permission Denied?