Talking to NEUMA: our REST Services Interface

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.

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.

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.

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.