MusicBrainz API/XML: Difference between revisions
From MusicBrainz Wiki
Jump to navigationJump to search
Reosarevok (talk | contribs) (Redirected page to MusicBrainz API) Tag: New redirect |
|||
(171 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. --warp. |
|||
==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> |
|||
Release-groups can be filtered on type, and releases can be filtered on type and/or status. For example, if you want all the Live Bootleg releases by Metallica: |
|||
/ws/2/release?artist=65f4f0c5-ef9e-490c-aee3-909e7ae6b2ab&status=bootleg&type=live |
|||
Or all albums and EPs by Autechre: |
|||
/ws/2/release-group?artist=410c9baf-5469-44f6-9852-826524b80c61&type=album|ep |
|||
Note that filtering is mandatory, if you don't specify type or status the release and release-group resources will not return any results. |
|||
===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, aliases |
|||
/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== |
|||
You can perform a lookup of an entity when you have the MBID for that entity: |
|||
lookup: /<ENTITY>/<MBID>?inc=<INC> |
|||
===Subqueries=== |
|||
The inc= is parameter allows you to request more information to be included about |
|||
the entity. Any of the entities directly linked to the entity can be included. |
|||
/ws/2/artist recordings, releases, release-groups, works |
|||
/ws/2/label releases |
|||
/ws/2/release-group artist, releases |
|||
/ws/2/work artist |
|||
/ws/2/recording artist, releases |
|||
/ws/2/release artist, label, recordings, release-groups |
|||
All lookups which include releases allow a seperate status= argument to further |
|||
narrow down the type of releases you are looking for. All lookups which include |
|||
release-groups allow a type= argument to narrow down the release-groups. |
|||
Note that the number of linked entities returned is always limited to X, |
|||
if you need the remaining results, you will have to perform a browse request. |
|||
: <span style="color:#888">〜 How large should X be? can it be the same for all resources or should it be tweaked based on either of the two entity types involved? --warp.</span> |
|||
=== inc= arguments which affect subqueries === |
|||
Some additional inc= parameters are supported to specify how much of the data about |
|||
the linked entities should be included: |
|||
- discids include discids for all media in the releases |
|||
- media include media for all releases, this includes the # of tracks on each medium. |
|||
- puids include puids for all recordings |
|||
- isrcs include isrcs for all recordings |
|||
- iswcs include iswcs for all works |
|||
- various-artists include only those releases on which the artist appears on one of the tracks, |
|||
but not in the artist credit for the release itself (this is only valid on a |
|||
/ws/2/artist?inc=releases request). |
|||
: <span style="color:#888">〜 ISWC should IMO always be provided for works, and thus not require a inc=iswcs. Indeed it is just a property of a work, like e.g. the country of an artist. --murdos.</span> |
|||
As a special case, artists will be included for recordings on a /ws/2/release?inc=artist+recordings lookup. |
|||
To get all ISWCs for ABBA for example, you could do: |
|||
/ws/2/artist/d87e52c5-bb8d-4da8-b941-9f4928627dc8?inc=works+iswcs |
|||
(Just using 'inc=iswcs' would not return any iswcs, you need to include works to use 'iswcs'). |
|||
=== Misc inc= arguments === |
|||
- aliases include artist, label or work aliases |
|||
=== Relationships === |
|||
inc= arguments to include relationships work exactly like they do in /ws/1: |
|||
- artist-rels |
|||
- label-rels |
|||
- recording-rels |
|||
- release-rels |
|||
- release-group-rels |
|||
- url-rels |
|||
- work-rels |
Latest revision as of 20:10, 10 July 2020
Redirect to: