distributed-text-services/specifications

Status code, when a level is not available in the navigation endpoint

ingoboerner opened this issue · 2 comments

ingoboerner commented

What would be the best http status code to return, when someone requests a level that is not available, e.g. exceeds the maximum cite depth?

Example in the documentation:
https://distributed-text-services.github.io/specifications/Navigation-Endpoint.html#example-2-requesting-all-descendants-of-a-textual-resource-at-a-specified-level

What should be returned, when the request would have been:
/api/dts/navigation/?id=urn:cts:greekLit:tlg0012.tlg001.opp-grc5&level=5

404 – Not found? or 400 Bad Request? or some other custom status code?

PonteIneptique commented

It's a good question, we'll need to address this in the meeting.
Right now, I would lean towards 404. Or 412 but I am not sure I understand it quite well.

monotasker commented

From the 1-alpha1 release docs:

A Navigation endpoint request may specify a level in a Resource's CitationTree that does not exist. One may, e.g., provide a down value of 3 when only 1 lower level exists in the Resource's CitationTree. In this case the member array will simply include any CitableUnits that do satisfy the parameters.

If there are no CitableUnits at all that satisfy the parameters of a Navigation endpoint request:

  • the request must not raise an error
  • the Navigation object member property must be an empty array.

For example, if the ref is at the bottom level of the queried CitationTree, and a down of 2 is provided in the request, the response will provide an empty array as its member value.

We published the resolution of this issue during the tech committee meeting on 2024-03-08

commit a0db8ca
release https://github.com/distributed-text-services/specifications/releases/tag/1-alpha1

This is an alpha release and we are looking for feedback!