Difference between revisions of "MusicBrainz API/XML"

From MusicBrainz Wiki
(Redirected page to MusicBrainz API)
(Tag: New redirect)
(176 intermediate revisions by 38 users not shown)
Line 1: Line 1:
=XML Web Service v2=
#REDIRECT [[MusicBrainz API]]
This is my proposal on how V2 of the [[XML_Web_Service]] should work.
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 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:
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:
Or all albums and EPs by Autechre:
: <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>
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>
You can perform a lookup of an entity when you have the MBID for that entity:
  lookup:  /<ENTITY>/<MBID>?inc=<INC>
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).
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:
(Just using 'inc=iswcs' would not return any iswcs, you need to include works to use 'iswcs').
=== Misc inc= arguments ===
  - aliases          include artist or label 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: