Talking to NEUMA: our REST Services Interface
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:
That's all there is to know.
Data access services
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.
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.
- score.xml. The MusicXML document.
- mei.xml. The MEI document.
- score.ly. The Lilypond document.
- score.pdf. The PDF rendering (Lilypond).
- score.png. The PNG rendering (Lilypond).
- preview.png. The first line of the score (Lilypond).
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.
To come soon