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.
  4. score.pdf. The PDF rendering (Lilypond).
  5. score.png. The PNG rendering (Lilypond).
  6. preview.png. The first line of the score (Lilypond).

Search service

To come soon