XML Web Service/Version 2/Examples

From MusicBrainz Wiki
Jump to navigationJump to search

NOTE: the following is WRONG. should only accept entity-lists in the POST request body. will update soon. --warp.

Submitting tags example

The following will show you how you can submit tags using just 'curl'. On Mac OS X curl should be available by default, it is also easily available on most linux distributions.

First, create an XML file with the tags you want to submit:

warp@bullet-bill:~/tags$ cat body.xml
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">
        <artist id="a16d1433-ba89-4f72-a47b-a370add0bb56">
                <user-tag><name>country schlager thrash gabber</name></user-tag>
        <recording id="eb818aa4-d472-4d2b-b1a9-7fe5f1c7d26f">
                <user-tag><name>thrash metal</name></user-tag>

NOTE: the MBIDs used in the example above are fake, do not try to submit that example verbatim.

If you want, you can validate your XML using our schema. For this you will need a tool to check an xml document against a RelaxNG schema. For this you can use 'jing', which should be available in most linux distributions (or download it from http://code.google.com/p/jing-trang).

warp@bullet-bill:~/tags$ curl --silent http://svn.musicbrainz.org/mmd-schema/trunk/schema/musicbrainz_mmd-2.0.rng -o musicbrainz_mmd-2.0.rng
warp@bullet-bill:~/tags$ jing musicbrainz_mmd-2.0.rng body.xml 

If there are no errors, jing will not output anything. If you do have an error, you will see something like this:

warp@bullet-bill:~/tags$ jing musicbrainz_mmd-2.0.rng body.xml 
/home/warp/tags/body.xml:14:27: error: text not allowed here; expected element "name"
/home/warp/tags/body.xml:14:38: error: element "user-tag" incomplete; missing required element "name"

Now that the body for your request is ready, use curl to perform a digest request (make sure to use your username/password):

warp@bullet-bill:~/tags$ curl --header 'Content-Type: application/xml; charset=UTF-8' \
> --silent --digest --user example:password --data-binary @body.xml \
> 'http://test.musicbrainz.org/ws/2/tag?client=example-0.3.7' | xmlindent
<?xml version="1.0" encoding="UTF-8"?>
<metadata xmlns="http://musicbrainz.org/ns/mmd-2.0#">

I've used 'xmlindent' in the example above to make the response a bit more readable for humans. You can just leave that off if your system doesn't have xmlindent.

NOTE: the above example uses 'test.musicbrainz.org' as the server. You probably want to use that server, or your own development server during development. When NGS has been released you should replace this with 'musicbrainz.org' in your production code.