search

distributed-text-services / specifications

Specifications for the DTS API
https://w3id.org/dts
28 stars 9 forks source link

Document endpoint : documentation inconsistency in the "response header" part ? #239

Closed rerouj closed 7 months ago

rerouj commented 7 months ago

the document endpoint documentation at example 3 shows the navigation's links in the response header after requesting a milestone reference (start=1.1.1 end=1.1.2). When reading the response header, it looks like the provided links does not imply a specific slicing strategy.

Indeed, the next link is showing the same milestone range on the next parent reference (start: 1.2.1, end: 1.2.2).

</dts/api/document/?id=urn:cts:latinLit:phi1318.phi001.perseus-lat1&start=1.2.1&end=1.2.2>; rel=”next”

On the other hand, the last link is showing the same milestone gap but on the last items of the last parent which is on the last reference of the root element (start : 5.5.6, end 5.5.7)

</dts/api/document/?id=urn:cts:latinLit:phi1318.phi001.perseus-lat1&start=5.5.5&end=5.5.6>; rel=”last”

The next link is traversing the document horizontally - if I can say - through the first parent reference, where the last link seem to follow the natural path of the text. Could you clarify if the different links are supposed to cover the same slicing and navigation strategy ? Is the client supposed to hit the "first/last" reference when following the "prec/next" link ?

PonteIneptique commented 7 months ago

@rerouj I think this is part of the thing that have been rewritten during last week workshop. Link headers have been mostly dropped in the Document endpoint, except for a single link towards the Collection endpoint.

See #238

rerouj commented 7 months ago

Thank you @PonteIneptique for the quick answer !

PonteIneptique commented 7 months ago

Link headers are a should now, because of our level 0 static implementation compatibility layer. See https://github.com/distributed-text-services/specifications/blob/1bd713b1ddb097ed952315667b1edab0efef692a/Document-Endpoint.md#header

PonteIneptique commented 7 months ago

(If you are implementing, I'd recommend to have a look primarily to the state of this branch of @monotasker repository ;) )

PonteIneptique commented 7 months ago

And welcome to the band !

rerouj commented 7 months ago

(If you are implementing, I'd recommend to have a look primarily to the state of this branch of @monotasker repository ;) )

Really good job from @monostaker ! I'll add these changes in the next version of my own implementation.

PonteIneptique commented 7 months ago

The technical committee had a three days long workshop to iron out the specs. Lots of things are gonna be better and clearer, both for client and server providers.

monotasker commented 6 months ago

We published the resolution of this issue during the tech committee meeting on 2024-03-08 commit https://github.com/distributed-text-services/specifications/commit/a0db8ca0f5b9ef2e208baae7cacd8e2b6108685b release https://github.com/distributed-text-services/specifications/releases/tag/1-alpha1