History:Development/XML Web Service/Version 1
From MusicBrainz Wiki
Jump to navigationJump to search
This page describes the next generation XML based web service for MusicBrainz. Initially we will discuss the proposed XML and its Relax NG schema for expressing MusicBrainz (and music in general) metadata. Once we hammer that out, we'll discuss the URL scheme proposed by Matthias Friedrich.
Use Cases
This new web service will have the following use cases:
- Retrieve artist (via mbid)/album (via mbid/cdid)/track (via mbid)
- Each of these should return a minimal amount of data and have options to return more detailed data:
- artist: optional list of albums
- album: optional artist info, cdids, release info, list of tracks
- track: optional artist info
- Each of these should return a minimal amount of data and have options to return more detailed data:
- Retrieve a list of tracks that match a given trmid
- same arguments that apply to track info should be used here
- Full text search of the DB (via lucene query)
- Login to MB
- Submit trmids (after login)
- Check donation status of user (for showing pop-ups in Picard)
- Lookup track (like MBQ_FileLookup)
URL Schema
The web service will be REST style, which means we need a structure for our URL namespace. The schema discussed below allows for future development (using versions) and different types of output (using content negotiation). There will be at least three types of resources: artist, album and track, but more can be added later. You can either request a resource by its ID or apply a filter to the set of all resources of a type.
General query parameters:
| type | xml, html, whatever we want to support |
| inc | A list of space separated values describing how much detail should be included in the output. If there is no 'inc' parameter, just the basic data for a resource is returned. For artists that would be name and sortName. |
artist resources
Parameters for http://musicbrainz.org/ws/1/artist/MBID:
| inc | A list of data to be included from albums, relations, ... |
| thingy | thingy thingy thingy! |
Parameters for http://musicbrainz.org/ws/1/artist/:
| name | Fetch a list of artists with a matching name |
| limit | Limit the number of artists returned |
album resources
Parameters for http://musicbrainz.org/ws/1/album/MBID:
| blah | do something |
| thingy | thingy thingy thingy! |
Parameters for http://musicbrainz.org/ws/1/album/:
| name | Fetch a list of albums with a matching name |
| limit | Limit the number of albums returned |
track resources
Parameters for http://musicbrainz.org/ws/1/track/MBID:
| blah | do something |
| thingy | thingy thingy thingy! |
Parameters for http://musicbrainz.org/ws/1/track/:
| name | Fetch a list of tracks with a matching name |
| limit | Limit the number of tracks returned |
XML Format
The following sample XML document describes a partial album:
<?xml version="1.0" encoding="UTF-8"?>
<mb:metadata xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:mb="http://musicbrainz.org/ns/mb/1/"
xmlns:az="http://www.amazon.com/gp/aws/landing.html#">
<mb:album-list>
<mb:album id="8f468f36-8c7e-4fc1-9166-50664d267127" type="album">
<dc:title>Dummy</dc:title>
<mb:counts track="11" cdid="10" trmid="73"/>
<az:asin>B000001FI7</az:asin>
<mb:artist id="8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11" begin="1991" end="2011">
<dc:title>Portishead</dc:title>
<mb:sortName>Portishead</mb:sortName>
</mb:artist>
<mb:release-list>
<mb:release date="1994-10-17" country="us"/>
</mb:release-list>
<mb:cdid-list>
<mb:cdid id="D5LsXhbWwpctL4s5xHSTS_SefQw-"/>
</mb:cdid-list>
<mb:track-list>
<mb:track id="b5d7d380-f43a-4c1f-a5de-694150b093ac" duration="306200">
<dc:title>Mysterons</dc:title>
<!-- This block is shown only if the track artist != album artist -->
<mb:artist id="8f6bd1e4-fbe1-4f50-aa9b-94c450ec0f11" begin="1991" end="2011" type="group">
<dc:title>Portishead</dc:title>
<mb:sortName>Portishead</mb:sortName>
</mb:artist>
<mb:trmid-list>
<mb:trmid id="58bdde9c-9c47-487a-94ae-1e9c4001bd3d"/>
</mb:trmid-list>
</mb:track>
</mb:track-list>
</mb:album>
</mb:album-list>
</mb:metadata>
The above XML parses and validates with the following Relax NG schema:
<?xml version="1.0" encoding="UTF-8"?>
<!--
<hr>
Relax NG Schema for MusicBrainz XML Metadata Version 0, draft 1
Copyright (c) 2004 Robert Kaye
The schema is released under the Creative Commons
Attribution-ShareAlike 2.0 license.
http://creativecommons.org/licenses/by-sa/2.0/
<hr>
TODO:
- Constrain text values and attributes
- Add AR support
- Add extensibility
-->
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
xmlns:mb="http://musicbrainz.org/ns/mb/1/"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:az="http://www.amazon.com/gp/aws/landing.html#">
<start>
<ref name="metadata"/>
</start>
<define name="metadata">
<element name="mb:metadata">
<optional>
<ref name="artist-list"/>
</optional>
<optional>
<ref name="album-list"/>
</optional>
<optional>
<ref name="track-list"/>
</optional>
</element>
</define>
<define name="album-list">
<element name="mb:album-list">
<oneOrMore>
<ref name="album-entity"/>
</oneOrMore>
</element>
</define>
<define name="artist-list">
<element name="mb:artist-list">
<oneOrMore>
<ref name="artist-entity"/>
</oneOrMore>
</element>
</define>
<define name="track-list">
<element name="mb:track-list">
<oneOrMore>
<ref name="track-entity"/>
</oneOrMore>
</element>
</define>
<define name="artist-entity">
<element name="mb:artist">
<optional>
<attribute name="id"/>
</optional>
<optional>
<attribute name="begin"/>
</optional>
<optional>
<attribute name="end"/>
</optional>
<optional>
<attribute name="group"/>
</optional>
<optional>
<attribute name="type"/>
</optional>
<element name="dc:title">
<text/>
</element>
<optional>
<element name="mb:sortName">
<text/>
</element>
</optional>
</element>
</define>
<define name="album-entity">
<element name="mb:album">
<optional>
<attribute name="id"/>
</optional>
<optional>
<attribute name="type"/>
</optional>
<optional>
<attribute name="status"/>
</optional>
<element name="dc:title">
<text/>
</element>
<optional>
<element name="mb:counts">
<optional>
<attribute name="track"/>
</optional>
<optional>
<attribute name="cdid"/>
</optional>
<optional>
<attribute name="trmid"/>
</optional>
<text/>
</element>
</optional>
<optional>
<element name="az:asin">
<text/>
</element>
</optional>
<optional>
<ref name="artist-entity"/>
</optional>
<zeroOrMore>
<ref name="release-list"/>
</zeroOrMore>
<zeroOrMore>
<ref name="cdid-list"/>
</zeroOrMore>
<optional>
<ref name="track-list"/>
</optional>
</element>
</define>
<define name="track-entity">
<element name="mb:track">
<optional>
<attribute name="id"/>
</optional>
<optional>
<attribute name="duration"/>
</optional>
<element name="dc:title">
<text/>
</element>
<optional>
<ref name="artist-entity"/>
</optional>
<optional>
<ref name="album-entity"/>
</optional>
<optional>
<ref name="trmid-list"/>
</optional>
</element>
</define>
<define name="release-list">
<element name="mb:release-list">
<element name="mb:release">
<optional>
<attribute name="date"/>
</optional>
<optional>
<attribute name="country"/>
</optional>
</element>
</element>
</define>
<define name="cdid-list">
<element name="mb:cdid-list">
<element name="mb:cdid">
<attribute name="id"/>
</element>
</element>
</define>
<define name="trmid-list">
<element name="mb:trmid-list">
<element name="mb:trmid">
<attribute name="id"/>
</element>
</element>
</define>
</grammar>
