Alpheios CTS API

Overview

The Alpheios texts are available from a repository that supports a subset of the requests specified in the Canonical Text Services (CTS) Protocol.

The Alpheios CTS API is available at: http://repos1.alpheios.net/exist/rest/db/xq/CTS.xq?.

Supported Requests

We are working to make the Alpheios repository fully CTS compliant, and in the meantime, the following requests are currently supported:

GetCapabilities : this returns the TextInventory for the texts in the Alpheios repository.

GetValidReff: this returns a list of valid citation references for a given text in the repository, as specified by CTS urn.
e.g. the following request returns the list of books in the Iliad:
http://repos1.alpheios.net/exist/rest/db/xq/CTS.xq?request=GetValidReff&urn=urn:cts:greekLit:tlg0012.tlg001.alpheios-text-grc1

GetPassagePlus: this returns a specific passage as specified by passage urn.
e.g. the following request returns lines 1-10 of Book 1 of the Iliad:

http://repos1.alpheios.net/exist/rest/db/xq/CTS.xq?request=GetPassagePlus&urn=urn:cts:greekLit:tlg0012.tlg001.alpheios-text-grc1:1.1-1.10

Implementation

The Alpheios CTS API is implemented in XQuery, running in the eXist database server. The source code can found at http://alpheios.net/content/alpheios-cts-api. The main entry point is the CTS.xq file, and the implementation is primarily found in the cts.xquery file.

Installation

Prerequisites:

Restore from zip

  • Download the master.zip
  • Start the eXist database
  • Launch the eXist client
  • In the eXist client interface, select Tools, Restore
  • restore the master.zip file. At the prompt for password enter without supplying one.

Test Installation

This will put the CTS API at:

http://localhost:8080/exist/rest/db/xq/CTS.xq?

GetCapabilities:

http://localhost:8080/exist/rest/db/xq/CTS.xq?request=GetCapabilities

Should return the TextInventory with an entry for the Iliad

GetValidReff

http://localhost:8080/exist/rest/db/xq/CTS.xq?request=GetValidReff&urn=u...

Should return valid ref response (list of urns) for the books of the Iliad

GetPassagePlus

http://localhost:8080/exist/rest/db/xq/CTS.xq?request=GetPassagePlus&urn...

Returns line 1 of the iliad

Add Texts to the CTS Text Inventory

To add your text to the inventory, update the alpheios-cts-inventory.xml file in the eXist /db/repository/inventory collection

Then load your text in the directory you specify in the online element of the inventory. If you following the alpheios conventions, you will be able to load your text in the display ui. These conventions are:

/db/repository/[namespace]/[textgroup]/[work]/alpheios-text-[lng]1.xlm

e.g.

/db/repository/greekLit/tlg0012/tlg001/alpheios-text-ara1.xml

Known Issues

  • The CTS responses are not fully compliant with the latest version of the protocol. The teiHeader should be removed from the passage response.
  • Subreference queries do work, but they use the wrong separator between the passage and the subreference - : instead of @. That is, urn:cts:greekLit:tlg0012.tlg001.alpheios-text-grc1:1.1:ἄειδε[1] instead of the correct form: urn:cts:greekLit:tlg0012.tlg001.alpheios-text-grc1:1.1@ἄειδε[1]
  • CTS urns which include the exemplar component are not yet supported
  • abstraction to the notional work level is not yet supported (i.e. a request for a urn which does not include a version component will fail
  • Passage range only supports numeric citation scheme units
  • Supported citation scheme unit labels are hardcoded
  • Passage range response wraps each passage in a repeat of the xml hierachy
  • There are some hard-coded assumptions about the use of the @n attribute in the citation scheme that need to be removed

Roadmap

The following items are on the roadmap for the Alpheios CTS API

  • Address the known issues identified above
  • Refactor the implementation to have a clean separation between the API and secondary supporting functionality
  • support alpha-numeric citation scheme units
  • remove internal hardcoding of citation scheme units
  • Rational approach to returning passage ranges