ListObjects should indicate whether the returned response is complete or not

[rhamzeh]

Reported by: Rouven on Discord
Summary: Currently a user has no way of knowing whether the results returned by the ListObjects (or StreamedListObjects) endpoint is a complete set of all the object that the user has that relation to, or only a partial set.

This is mainly due to: listObjectsDeadline and listObjectsMaxResults.

We have earlier discussed returning either a header or a field in the body to represent partial results:

In the response body:
e.g:

{
  "objects": [...],
  "is_complete": true // or is_partial: false
}

or

In the header: e.g. X-OpenFGA-ListObjects-Response-Complete: true or similar

Rouven suggested that they actually prefer that the endpoint return an Error (e.g. deadline_exceeded) in that case, but they would be OK with an indicator in the response.

[Oscmage]

This feels like a critical feature of list objects that I almost deem necessary to be able to use OpenFGA in production. I would similarly to Rouven prefer that the endpoint gave me deadline exceeded and failed than having to deal with partial results.

I was very confused when I saw partial results and assumed it was a bug in the implementation itself. Even if is_complete was returned I am not sure that is something you would reflect about when integrating with OpenFGA.