Replicating functionality from / deprecating scaife-cts.perseus.org

[jacobwegner]

The changes provided by #566 (deployed in the v2022-08-30-001 release have allowed us to remove the dependency on scaife-viewer/scaife-cts-api (powering scaife-cts.perseus.org.

I now realize that there have been other users of scaife-cts.perseus.org that were not aware of the changes in v2022-08-30-001 release or that content is no longer being updated there.

This issue serves to do a few things:

• Help provide a breadcrumb as to why content is no longer being updated on scaife-cts.perseus.org
• List the currently available APIs on https://scaife.perseus.org/
• Provide a place for users to request similar functionality from scaife-cts.perseus.org directly on https://scaife.perseus.org/
• Provide accountability to @jacobwegner to properly wind down scaife-cts.perseus.org

As part of development of Beyond Translation, there will also be a GraphQL API that should be able to replicate the functionality from scaife-cts.perseus.org.

Current APIs on scaife.perseus.org

(also formatted as a list)

Purpose	Endpoint name	scaife-cts	scaife equivalent
Retrieve the XML for a passage of a text	GetPassage	https://scaife-cts.perseus.org/api/cts?request=GetPassage&urn=urn:cts:greekLit:tlg0059.tlg002.perseus-grc2	https://scaife.perseus.org/library/urn:cts:greekLit:tlg0059.tlg002.perseus-grc2/cts-api-xml/
Retrieve children references	GetValidReff	https://scaife-cts.perseus.org/api/cts?request=GetValidReff&urn=urn:cts:greekLit:tlg0059.tlg002.perseus-grc2	https://scaife-dev.perseus.org/library/urn:cts:greekLit:tlg0059.tlg002.perseus-grc2/cts-api-xml/reffs/?level=1
Retrieve a list of available resources	GetCapabilities	https://scaife-cts.perseus.org/api/cts?request=GetCapabilities	https://scaife.perseus.org/library/json/
Retrieve a passage and its metadata	GetPassagePlus	https://scaife-cts.perseus.org/api/cts?request=GetPassagePlus&urn=urn:cts:greekLit:tlg0059.tlg002.perseus-grc2:17	https://scaife.perseus.org/library/passage/urn:cts:greekLit:tlg0059.tlg002.perseus-grc2:17/json/
Retrieve previous and following passage of a given urn	GetPrevNextUrn	https://scaife-cts.perseus.org/api/cts?request=GetPrevNextUrn&urn=urn:cts:greekLit:tlg0059.tlg002.perseus-grc2:17	Headers (Gist) from https://scaife.perseus.org/library/passage/urn:cts:greekLit:tlg0059.tlg002.perseus-grc2:17/json/
Retrieve the first child of given URN	GetFirstUrn	https://scaife-cts.perseus.org/api/cts?request=GetFirstUrn&urn=urn:cts:greekLit:tlg0059.tlg002.perseus-grc2	https://scaife.perseus.org/library/urn:cts:greekLit:tlg0059.tlg002.perseus-grc2/json/ (.first_passage)
Retrieve metadata about given edition or translation	GetLabel	https://scaife-cts.perseus.org/api/cts?request=GetLabel&urn=urn:cts:greekLit:tlg0059.tlg002.perseus-grc2	https://scaife.perseus.org/library/urn:cts:greekLit:tlg0059.tlg002.perseus-grc2/json/

Please leave a comment on this issue if there is a desire to have a particular scaife-cts-api endpoint ported over "verbatim", and we'll see what we can do to accomodate!

[dasmiq]

This is a great summary! One thing that seems missing for our use case is that we'd like to get a list of all the citable locations in a text. In the old API, the capabilities told us how many levels of citation there were (e.g., book.line vs. book.chapter.section) and then we could call GetValidReff with the "level" argument, e.g.:
https://scaife-cts.perseus.org/api/cts?request=GetValidReff&urn=urn:cts:greekLit:tlg0003.tlg001.perseus-grc2&level=3

but the equivalent JSON call seems to only give us the top level of books:
https://scaife.perseus.org/library/urn:cts:greekLit:tlg0003.tlg001.perseus-grc2/json/

Is there some way to get a list of all sections with the JSON API? This is especially helpful for poetry, so that we can just get each line separately and not have to split the cards up ourselves.

[jacobwegner]

@dasmiq I had tried to reply here yesterday, but it looks like it didn't go through...sorry!

You're correct that the current endpoints only support the "top level".

The GraphQL API we're working on will support multiple levels, but in the interim, I'll backport GetValidReff functionality to the JSON API.

I'll work to get things deployed to a dev instance next week and will bump this issue when that has been completed.

[jacobwegner]

@dasmiq: The new endpoint is available for preview here:

https://scaife-dev.perseus.org/library/urn:cts:greekLit:tlg0081.tlg001.perseus-grc2/cts-api-xml/reffs/?level=1

https://scaife-dev.perseus.org/library/urn:cts:greekLit:tlg0081.tlg001.perseus-grc2:1/cts-api-xml/reffs/?level=1

It should work just as the old GetValidReff request on scaife-cts.perseus.org.

I will get it "promoted" to scaife.perseus.org early next week.

[dasmiq]

Fantastic! Thanks very much, Jake. Have a great weekend!

…

On Fri, Jun 23, 2023 at 6:21 PM Jacob Wegner ***@***.***> wrote: @dasmiq <https://github.com/dasmiq>: The new endpoint is available for preview here: https://scaife-dev.perseus.org/library/urn:cts:greekLit:tlg0081.tlg001.perseus-grc2/cts-api-xml/reffs/?level=1 https://scaife-dev.perseus.org/library/urn:cts:greekLit:tlg0081.tlg001.perseus-grc2:1/cts-api-xml/reffs/?level=1 It should work just as the old GetValidReff request on scaife-cts.perseus.org. I will get it "promoted" to scaife.perseus.org early next week. — Reply to this email directly, view it on GitHub <#590 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALL6MP4K26PK4LYO66AF5DXMYJGFANCNFSM6AAAAAAZQPQS7I> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[jacobwegner]

@dasmiq:

The new endpoints have been promoted to scaife.perseus.org:

• https://scaife.perseus.org/library/urn:cts:greekLit:tlg0081.tlg001.perseus-grc2/cts-api-xml/reffs/?level=1
• https://scaife.perseus.org/library/urn:cts:greekLit:tlg0081.tlg001.perseus-grc2:1/cts-api-xml/reffs/?level=1

I've documented some of what I wrote in an email to you last week over in Infrastructure Architecture
.

I'm going to work on winding down scaife-cts.perseus.org soon; please let me know if the new endpoints are working for you or if there is anything that would be helpful to have ported over.

Thanks!

[jacobwegner]

I've just deployed a redirect from scaife-cts-dev.perseus.org to this issue with the hope that if others are depending on that endpoint that they see this issue and can provide further feedback.

I'll work on a public deprecation notice / plan for scaife-cts.perseus.org next.