XML Web Service / Version 2 / Examples

This page has not been reviewed by our documentation team (more info).

This page documents examples of using XML Web Service/Version 2

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-list>
        <artist id="a16d1433-ba89-4f72-a47b-a370add0bb56">
            <user-tag-list>
                <user-tag><name>country schlager thrash gabber</name></user-tag>
            </user-tag-list>
        </artist>
    </artist-list>
    <recording-list>
        <recording id="eb818aa4-d472-4d2b-b1a9-7fe5f1c7d26f">
            <user-tag-list>
                <user-tag><name>thrash metal</name></user-tag>
                <user-tag><name>metal</name></user-tag>
                <user-tag><name>korean</name></user-tag>
            </user-tag-list>
        </recording>
    </recording-list>
</metadata>
warp@bullet-bill:~/tags$

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 an existing username and 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#">
    <message>
        <text>OK</text>
    </message>
</metadata>
warp@bullet-bill:~/tags$ 

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.