MusicBrainz API/XML: Difference between revisions

From MusicBrainz Wiki
Jump to navigationJump to search
(New page: =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...)
 
(Redirected page to MusicBrainz API)
Tag: New redirect
 
(177 intermediate revisions by 38 users not shown)
Line 1: Line 1:
#REDIRECT [[MusicBrainz API]]
=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>).

: <span style="color:#888">〜 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.</span>

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

: <span style="color:#888">〜 we could make these mandatory, so that clients don't request all linked releases or release-groups out of laziness. --warp.</span>
: <span style="color:#888">〜 we may want to support type on releases too. --warp.</span>

===Paging===

Browse requests are the only requests which support paging, any browse request supports an 'offset=' argument to get more results.

: <span style="color:#888">〜 should we allow 'limit=' within a certain range? what about some kind of 'order-by='? --warp</span>

=== 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

: <span style="color:#888">〜 we probably want to allow a few more inc= arguments here, though we can always add more later. --warp.</span>

==Lookups==

Latest revision as of 20:10, 10 July 2020

Redirect to: