MusicBrainz API/XML
XML Web Service v2
This is my proposal on how V2 of the XML_Web_Service should work.
Introduction
We have six resources on our web service which represent core entities in our database:
artist, label, recording, release, release-group, work
We also provide a web service interface for the following non-core resources:
rating, tag, collection
On each entity resource, you can perform three different GET requests:
lookup: /<ENTITY>/<MBID>?inc=<INC> browse: /<ENTITY>?<ENTITY>=<MBID>&limit=<LIMIT>&offset=<OFFSET>&inc=<INC> search: /<ENTITY>?query=<QUERY>&limit=<LIMIT>&offset=<OFFSET>
Of these:
- Lookups are somewhat similar to lookups on /ws/1, and are documented further below.
- Browse requests are documented in the next chapter.
- Searches are implemented by the search server and are not currently documented here, suffice to say that <QUERY> uses the advanced query syntax understood by lucene. This is documented for the current server at http://wiki.musicbrainz.org/Text_Search_Syntax .
- ratings, tags and collections are not currently documented for /ws/2.
Browse
Browse requests are a direct lookup of all the entities directly linked to another entity. (with directly linked I am referring to any relationship inherent in the database, so no ARs). For example, you may want to see all releases on netlabel ubiktune:
/ws/2/release?label=47e718e1-7ee4-460c-b1cc-1192a841c6e5
Note that browse requests are not searches, in order to browse all the releases on the ubiktune label you will need to know the MBID of ubiktune.
Linked entities
The following list shows which linked entities you can use in a browse request:
/ws/2/artist recording, release, release-group, work /ws/2/label release /ws/2/release-group artist, release /ws/2/work artist /ws/2/recording artist, release /ws/2/release artist, label, recording, release-group
As a special case, release also allows track_artist, which is intended to allow you to browse various artist appearances for an artist. It will return any release where the artist appears in the artist_credit for a track, but NOT in the artist_credit for the entire release (as those would already have been returned in a request with artist=<MBID>).
- 〜 I think track_artist as described above is important, otherwise you will get client software requesting all recordings for an artist, followed by release requests for each of the recordings found earlier. --warp.
Furthermore, release-groups can be filtered on type, and releases can be filtered on status. For example, if you only want Official and Promotional releases by Akira Kiteshi:
/ws/2/release?artist=1dc316e9-884a-48fb-8b30-a72bd606a776&status=official|promotional
Or all albums and EPs by Autechre:
/ws/2/release-group?artist=410c9baf-5469-44f6-9852-826524b80c61&type=album|ep
- 〜 we could make these mandatory, so that clients don't request all linked releases or release-groups out of laziness. --warp.
- 〜 we may want to support type on releases too. --warp.
Paging
Browse requests are the only requests which support paging, any browse request supports an 'offset=' argument to get more results.
- 〜 should we allow 'limit=' within a certain range? what about some kind of 'order-by='? --warp
inc=
Just like with normal lookup requests, the server can be instructed to include more data about the entity using an 'inc=' argument. Supported values for inc= are:
/ws/2/artist aliases /ws/2/label aliases /ws/2/release-group artist /ws/2/work artist /ws/2/recording artist /ws/2/release artist, label
In addition to the inc= values listed above, all entities (except release) support:
tags, ratings, user-tags, user-ratings
- 〜 we probably want to allow a few more inc= arguments here, though we can always add more later. --warp.