Talking to NEUMA: our REST Services Interface

Neuma proposes a RESTful interface to communicate with the digital library. All documents exchanged with Neuma are JSON-encoded.

Principles

Neuma exposes to the REST API a structure based on two types of resources: Corpus and Opus. Each corpus is a container with (sub-)corpora and/or a list of opera. The structure of a collection is therefore a hierarchy root at as pseudo-corpus _all. Internal nodes are corpuses, leaves are opuses.

  • IDs. Both Corpus and Opus resources are uniquely identified with an id The form of an id is Ci:Cj:...:R: it is built from the sequence of Corpus ids from the root to the resource R, separated by semicolons. For instance the id of resource o2 is c1:c4:o2
  • Paths. The path to a resource is expressed with the standard form Ci/Cj/Ck/.../R, where R is either a corpus or an opus id. On the above figure, /c1/c3 refers to Corpus c3, and /c1/c4/o2 refers to Opus o2. Basically, the path is the resource's id, where semicolons are replaced by slashes.
  • Services. In addition to simple GET requests that retrieve a JSON representation, resources supply services, conventionally named with a leading underscore. So, for instance, /c1/c3/_opera returns the list of opera in corpus c3.

That's all there is to know.

Collections access services

All collections access services are rooted at http://neuma.huma-num.fr/rest/collections

Corpora

Given a corpus, you can retrieve the list of sub-corpora with the _corpora service. The top-level corpora are obtained by calling the service: curl -X GET "/rest/collections/_corpora/"

Test it: /rest/collections/_corpora

Given a corpus id, replace all the semicolons by a slash top to obtain the path. A GET retrieves the corpus representation. curl -X GET "/rest/collections/psautiers"

Test it: /rest/collections/psautiers

Sub-corpora can it turn be obtained by calling the _corpora service, and so on so forth.

curl -X GET "/rest/collections/psautiers/_corpora"

Test it: /rest/collections/psautiers/_corpora.

Opera

The list of opera in a corpus is obtained with the _opera service.

Test it: /rest/collections/psautiers/godeau1656/_opera.

The _opera request can be paginated thanks to the from and size parameters.

curl -X GET "/rest/collections/psautiers/godeau1656/_opera?from=10&size=30"

An Opus stores a set of files: the MusicXML document, the MEI document, the PDF and PNG rendering obtained from Lilypond, etc. You can check the list of files available with the _files Opus service.

curl -X GET "/rest/collections/psautiers/godeau1656/1/_files"

Test it: /rest/collections/psautiers/godeau1656/1/_files.

Here is the list of possible files names.

  1. score.xml. The MusicXML document.
  2. mei.xml. The MEI document.
  3. score.ly. The Lilypond document.

Search service

To come soon