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

All services are rooted at http://scorelib.huma-num.fr/rest.

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.

  • 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.

Data access services

Corpora

Given a corpora, you can retrieve the list of sub-corpora with the _corpora service. The top-level corpora are obtained by calling the service on the root corpus.

curl -X GET "/rest/_corpora"

Test it: /rest/_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/psautiers"

Test it: /rest/psautiers

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

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

Test it: /rest/psautiers/_corpora.

Opera

The number of opera in a corpus is obtained with the _count_opera service.

curl -X GET "/rest/psautiers/godeau1656/_count_opera"

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

curl -X GET "/rest/psautiers/godeau1656/_opera"

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

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

curl -X GET "/rest/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/psautiers/godeau1656/1/_files"

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

Here is the list of the 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).

Computation Services

Computation services

Lilypond service

You can get a Lilypond representation of a score by PUTting either a MusicXML or a MEI file to a corpus. The service name is _lilypond, and it return a raw Lilypond text file. If something goes wrong, the service returns a non-OK HTTP code (i.e., something different from 200), and a JSON body with the error message.

Exemple: curl -X PUT "http://scorelib.huma-num.fr/rest/psautiers/godeau1656/_lilypond -d @score.xml"

The purpose of sending the request to a specific corpus is to apply the style of this corpus. For psautiers for instance, this means mensural-like note heads, and no bars. If you wish to use a neutral style, choose the timbres corpus.

Search service

To come soon

 
  • Hébergement, stockage et gestion de l'application sur la grille de services de la TGIR Huma-Num