ingoboerner
commented
3 years ago Code
- branch
dtsof the dracor-api: https://github.com/dracor-org/dracor-api/tree/dts - dts endpoints are in a separate xQuery module named "dts": https://github.com/dracor-org/dracor-api/blob/dts/modules/dts.xqm ; used restXQ and a lot of quirky helper functions
Demo
A a demo of the DraCor DTS implementation is available at https://staging.dracor.org/api/dts
Example queries:
- browse all 15 drama corpora via the collection endpoint: https://staging.dracor.org/api/dts/collections
- list all 1500 plays in the biggest corpus – "FreDraCor" (French Drama Corpus), or some of the more exotic and smaller ones, e.g. two plays in the Bashkir language https://staging.dracor.org/api/dts/collections?id=bash
- example of a single play in the collection endpoint: https://staging.dracor.org/api/dts/collections?id=ger000017 (is
citeStructureused correctly, see section "to do"?) - list structural divisions of a play via the navigation endpoint: https://staging.dracor.org/api/dts/navigation?id=ger000017&level=2
- list all scenes in an act via the navigation endpoint: https://staging.dracor.org/api/dts/navigation?id=ger000017&ref=body.div.2
- Retrieve a whole document: https://staging.dracor.org/api/dts/documents?id=rus000047
- or a a fragment, e.g. the setting description: https://staging.dracor.org/api/dts/documents?id=rus000047&ref=front.set.1 or the cast list https://staging.dracor.org/api/dts/documents?id=ger000480&ref=front.div.3 ,
- an act https://staging.dracor.org/api/dts/documents?id=ger000088&ref=body.div.3
- and a scene https://staging.dracor.org/api/dts/documents?id=ger000088&ref=body.div.3.div.5
- list the parent collection of a single play using the parameter
nav: https://staging.dracor.org/api/dts/collections?id=ger000088&nav=parents
limitations, to do
xml:ids are not available on structural sub-divisions of a play, so I had to use the structural information (tei:div) to build a reference system- didn't have time nor did I know how to best implement a machine readable documentation of the endpoints;
- didn't have time to dive into ranges
Collections endpoint
- I didn't have time to implement the paging feature, which would become in handy, when browsing the bigger collections, e.g. https://staging.dracor.org/api/dts/collections?id=fre&page=1
- have to clarify, how to use
citeStructurecorrectly – currently it is used to outputciteTypein the sense of a type of a structural division, e.g. notates, that a drama has the structural divisionsactandscenevs. plays that are structured inscenes only.
Navigation endpoint
- super messy, ran out of time here, code needs refactroring for sure..
- e.g. not all combinations of parameters
refandlevelhave been implemented; it's possible, to request all structural divisions onlevel={1 or 2}from the document root, but not any level below that, even if theciteDepthwould allow it; it's only possible to list sub-sections of level 2 sections, e.g. scenes of an act (see above), but https://staging.dracor.org/api/dts/navigation?id=ger000017&ref=body would fail. https://staging.dracor.org/api/dts/navigation?id=ger000017&ref=body.div.1&level=1 works
Documents endpoint
- when requesting fragments, not all fields in the link header are included; especially the machine readable documentation is missing.
Proponent / Mentor
Ingo Boerner (@ingoboerner)
Brief Description
The aim is to implement a DTS endpoint to the DraCor-API (https://dracor.org/doc/api).
DraCor consists of corporas of dramas in eleven languages (German, Russian, French, Italian, Swedish, Spanish, Ancient Greek, Alsatian, Latin, Bashkir, and Tatar) as well as two additional author corpora (Shakespeare, Calderón), to which the platform offers several ways to access them: The plays are encoded in TEI-XML available under an open license via GitHub at https://github.com/dracor-org.
In addition to this "classical" modus operandi of corpus-based research, however, DraCor as an open digital ecosystem offers further interfaces and attached tools (network visualizations, Shiny App, Easy Linavis). Fundamental all this tools this is the DraCor REST API (https://dracor.org/doc/api), which provides functions for retrieving data in different formats (TEI, JSON, Plaintext, RDF, GEXF, GraphML) as well as some built-in analysis functionalities (e.g. on network metrics).
Coding skills needed
The DraCor-API is written in xQuery and implemented as an app in eXist-DB.
Team members
@cmil, @ingoboerner, @lehkost, @peertrilcke. People wanting to join are welcome, also to test and validate the implementation and to provide feedback.