search

ivoa-std / VOSpace

Virtual Observatory User Storage
Creative Commons Attribution Share Alike 4.0 International
3 stars 4 forks source link

Clarify description for getNode pagination #8

Open Zarquan opened 3 years ago

Zarquan commented 3 years ago

Based on discussion in the VOSpace mailing list 2021-June/003092.html.

The description for pagination of the getNode response is not particularly clear and a number of people have reported missing or skipping over it [1].

In addition, while the description or the Request parameters lists uri and limit, the description in the Response section refers to uri and offset.

The proposal is to move the description of how pagination works into a specific sub-section just for this.

Zarquan commented 3 years ago

The current text doesn't say what happens if the getNode request has a limit (or offset) parameter, but no uri parameter is specified. I'm guessing this means get limit children, starting from the first child.

Zarquan commented 3 years ago

The current example for getNode shows a case that isn't covered in the text of the specification. The request specifies the detail and uri parameters, but no value for limit (or offset).

In this case, should the response start the list of children from the child specified by the uri parameter and return all of the child nodes after that, or is the server allowed to apply it's own limit ?

Zarquan commented 3 years ago

The current specification does not say what happens if the uri parameter points to a node that is not a direct child of the target node.

Zarquan commented 3 years ago

The current specification does not say what happens if the uri or limit parameters are given in a getNode request for a DataNode. Probably they have no effect, but we should say.

Zarquan commented 3 years ago

The current specification says

.... the server may impose impose its own limit on the size of an individual response, splitting the results into more than one page if required

How does a client know that the server has applied a limit and there is another page ?

Zarquan commented 3 years ago

How does a client know that the server has applied a limit and there is another page ?

I don't think we can do this in this version. It will probably need a new version to solve it (see #11).

zonia3000 commented 3 years ago

The current specification does not say what happens if the uri parameter points to a node that is not a direct child of the target node.

I think that throwing an Invalid Argument fault is appropriate for this case.

Zarquan commented 3 years ago

I think that throwing an Invalid Argument fault is appropriate for this case.

I agree. We could try to fold this into the same change request as the clarifications to the text description, but given this is a change to the technical behaviour of the system, and the complexity of the edge cases it contains, I think we should put it in a separate issue and create a separate PullRequest for the change.

I have created a separate issue to discuss this change, see #12.

Zarquan commented 3 years ago

PR #16 makes a start on this