fix: editorials and flexibility in response entries payloads #7
Conversation
peppelinux
requested review from
selfissued,
MichaelFraser1999 and
lj-raidiam
Co-authored-by: Giuseppe De Marco <[email protected]>
MichaelFraser1999
temporarily deployed
to
github-pages
GitHub Actions
Inactive
Co-authored-by: Michael Fraser Raidiam <[email protected]>
selfissued
temporarily deployed
to
github-pages
GitHub Actions
Inactive
| | from_entity_id | OPTIONAL | Entity Identifier | If this parameter is present, the resulting list MUST be the subset of the overall ordered response starting from the index of the entity referenced with this paramter. The list's size MUST NOT exceed the server's chosen upper limit.<br><br>If the Entity Identifier that equals value of this parameter does not exist the HTTP status code 400 is returned and the content type `application/json` with the error code `entity_id_not_found`. TBD: Recommend client behavior on error. | | ||
| | limit | OPTIONAL | Positive Integer | Requested number of results included in the response.<br><br> If this parameter is present, the number of results in the returned list must not be greater than the minimum of the server's upper limit and the value of this parameter.<br><br>If this parameter is not present the server MUST fall back on the upper limit. | | ||
| | from_entity_id | OPTIONAL | Entity Identifier | If this parameter is present, the resulting list MUST be the subset of the overall ordered response starting from the index of the Entity referenced with this paramter. The list's size MUST NOT exceed the server's chosen upper limit.<br><br>If the Entity Identifier that equals value of this parameter does not exist the HTTP status code 400 is returned and the content type `application/json` with the error code `entity_id_not_found`. TBD: Recommend client behavior on error. | | ||
| | limit | OPTIONAL | Positive Integer | Requested number of results included in the response.<br><br> If this parameter is present, the number of results in the returned list SHOULD NOT be greater than the minimum of the server's upper limit and the value of this parameter.<br><br>If this parameter is not present the server MUST fall back on the upper limit. | |
There was a problem hiding this comment.
Why was this weakened from "must not" to "SHOULD NOT"? I would have expected "MUST NOT".
There was a problem hiding this comment.
because there might situations where the server doesn't support the requested limit or differently it doesn't support this configuration, forcing in the response the limit it configures by default
There was a problem hiding this comment.
other situation where the requestor doesn't know the server's limits
There was a problem hiding this comment.
@peppelinux I assume you are writing about an option where requested limit<server's upper limit e.g. there's a request with limit=1 and flood of API calls to fetch the entire set. It would be good to provide server with some control and/or let client discover what is supported. I recognize that we need to improve it, but I think that there are various ways to achieve it. Let me elaborate on it.
I see where you are going with that but I am afraid that this change may make it too open-ended i.e. with this wording if a client requests a limit=1 a server may return anything even beyond their upper limit or the requested limit.
If we reworded it to explicitly state that the upper limit (that is unknown to the client btw) is the absolute maximum then the server might return an arbitrary, yet not higher than upper limit, number of records to a client and would not be explicitly required to stay consistent between subsequent calls from a client intending to fetch the entire data set. Most the servers would be reasonable and consistent, but we would have to address it too.
Other potential problem is that the client in some drastic cases server might return more records than the client is able to process.
Having that said I think that we either:
- Improve it so it is more explicit that server can't return more than its upper limit in such cases and needs to be consistent across calls.
- Introduce the consistent lower limit that of records and exception that the server must return that many records when the requested limit is too low. We retain the original MUST NOT wording for the remaining cases.
- Introduce a
requested limit not supportederror response that would carry info on the supported range in the details. An upper and lower limit discovery option would be great too.
I would lean towards the 2 or 3. Any thoughts?
peppelinux
temporarily deployed
to
github-pages
GitHub Actions
Inactive
peppelinux
temporarily deployed
to
github-pages
GitHub Actions
Inactive
selfissued
temporarily deployed
to
github-pages
GitHub Actions
Inactive
Co-authored-by: Michael B. Jones <[email protected]>
MichaelFraser1999
dismissed stale reviews from selfissued and themself
via
4346a96
MichaelFraser1999
temporarily deployed
to
github-pages
GitHub Actions
Inactive
This PRs aims to align some terms and also tries to introduce some flexibilities for implementers that would use the endpoint to provide any sort of matedata without necessarly include the entity statements (since this might causes huge weigth in the response)