Difference between revisions of "MusicBrainz API/FAQ"

From MusicBrainz Wiki
(addling link to history: version one)
m
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
;Version 2? What happened to Version 1?
+
;What can I do with the MusicBrainz API?
:[[History:Development/XML Web Service/Version 1|Version 1]] of the Webservice served the original version of the MusicBrainz website, and is no longer in service
+
:You can look up information about a particular [[MusicBrainz Entity|MusicBrainz entity]] ("give me info about The Beatles"), browse the data to find entities connected to a particular entity ("show me all releases by The Beatles"), or search for entities matching a specific query ("show me all artists matching the query 'Beatles' so I can find the one I want and ask for more data").
;What can I do with WS/2?
+
;Who can use the MusicBrainz API? Is it free?
:There are three types of GET requests, as well as limited data submission, explained below.
 
;Who can use WS/2? Is it free?
 
 
:[[Live_Data_Feed|Non-commercial]] use of this web service is free; please see [https://metabrainz.org/supporters/account-type our commercial plans] or [[Contact_Us|contact us]] if you would like to use this service commercially.
 
:[[Live_Data_Feed|Non-commercial]] use of this web service is free; please see [https://metabrainz.org/supporters/account-type our commercial plans] or [[Contact_Us|contact us]] if you would like to use this service commercially.
 
;Do I need an API key?
 
;Do I need an API key?
:Currently, no. But you must have a meaningful [[XML_Web_Service/Rate_Limiting#Provide_meaningful_User-Agent_strings|user-agent string]].
+
:Currently, no. But you must have a meaningful [[MusicBrainz API/Rate_Limiting#Provide_meaningful_User-Agent_strings|user-agent string]].
 
;Do I need to provide authentication?
 
;Do I need to provide authentication?
 
:Data submission, as well as requests that involve user information, require [[wikipedia:Digest_access_authentication|digest]] authentication.
 
:Data submission, as well as requests that involve user information, require [[wikipedia:Digest_access_authentication|digest]] authentication.
 +
;Which formats can I get the data in?
 +
:The API was originally written to return XML, but nowadays it can also return JSON.
 +
;Is there any significant difference between the XML and JSON APIs?
 +
:For requesting data, the XML and JSON API are effectively equivalent. The XML API is the only one that allows [[MusicBrainz_API#Submitting_data|submitting data]] to MusicBrainz (but keep in mind only ratings, tags, barcodes and ISRCs can be submitted via the API at all; for most data additions you should use the website instead).
 
;Is there a limit to the number of requests I can make per second?
 
;Is there a limit to the number of requests I can make per second?
:'''Yes'''. See: [[XML_Web_Service/Rate_Limiting]]
+
:'''Yes'''. See [[MusicBrainz API/Rate_Limiting|our rate limiting rules]].
;What formats are available for the responses?
+
;This seems very complicated, can I see some examples?
:[[XML Web Service/Version 2|XML]] and [[Development/JSON_Web_Service|JSON]]
+
:Yes, we have [[MusicBrainz API/Examples|an example page]] showcasing some queries and showing the returned format you can expect for each.
;Are there language bindings for WS/2?
+
;Are there language bindings for the API?
:Yes. See: [[External_Resources#Access_MusicBrainz_using_external_APIs|external libraries]]
+
:Yes, in many different languages. See [[MusicBrainz API#Libraries|our list of external libraries]].
 
;What should I do if I encounter unexpected behaviour not covered in these docs?
 
;What should I do if I encounter unexpected behaviour not covered in these docs?
 
:You can ask question in [[IRC]] or in the [[discourse:|forums]].
 
:You can ask question in [[IRC]] or in the [[discourse:|forums]].
:Check to see if a ticket has been filed in the [http://tickets.musicbrainz.org/browse/MBS/component/10000#selectedTab=com.atlassian.jira.plugin.system.project%3Acomponent-summary-panel bug tracker], and if not consider writing one.
+
:Check to see if a ticket has been filed in the [https://tickets.metabrainz.org/issues/?jql=project%20%3D%20MBS%20AND%20component%20%3D%20%22Web%20service%22%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20priority%20DESC bug tracker], and if not consider writing one.
;What else should I know before I start using WS/2?
+
;What else should I know before I start using the API?
 
:It'd probably be helpful to know:
 
:It'd probably be helpful to know:
:*[[MusicBrainz_Database/Schema|how MusicBrainz is structured]]
+
:*[[MusicBrainz_Database/Schema|How MusicBrainz is structured]]
 
:*What [[mb:relationships/|relationships]] are available
 
:*What [[mb:relationships/|relationships]] are available
 +
;So you're on version 2 of the API then? What happened to version 1?
 +
:The version 1 of the API was designed with the data structure of the original (pre-2011) version of the MusicBrainz database in mind. It was deprecated in 2011 when we changed to our current data schema, and after running (without further updates) for several years to avoid breaking any tools using it, it was finally taken down in 2019.
 +
;Do you ever make breaking changes?
 +
:We try to avoid that, but sometimes we might need to do so. In those cases, they will be announced on [https://blog.metabrainz.org/category/musicbrainz+breaking-changes/ our blog], so consider following that!

Latest revision as of 05:08, 7 October 2020

What can I do with the MusicBrainz API?
You can look up information about a particular MusicBrainz entity ("give me info about The Beatles"), browse the data to find entities connected to a particular entity ("show me all releases by The Beatles"), or search for entities matching a specific query ("show me all artists matching the query 'Beatles' so I can find the one I want and ask for more data").
Who can use the MusicBrainz API? Is it free?
Non-commercial use of this web service is free; please see our commercial plans or contact us if you would like to use this service commercially.
Do I need an API key?
Currently, no. But you must have a meaningful user-agent string.
Do I need to provide authentication?
Data submission, as well as requests that involve user information, require digest authentication.
Which formats can I get the data in?
The API was originally written to return XML, but nowadays it can also return JSON.
Is there any significant difference between the XML and JSON APIs?
For requesting data, the XML and JSON API are effectively equivalent. The XML API is the only one that allows submitting data to MusicBrainz (but keep in mind only ratings, tags, barcodes and ISRCs can be submitted via the API at all; for most data additions you should use the website instead).
Is there a limit to the number of requests I can make per second?
Yes. See our rate limiting rules.
This seems very complicated, can I see some examples?
Yes, we have an example page showcasing some queries and showing the returned format you can expect for each.
Are there language bindings for the API?
Yes, in many different languages. See our list of external libraries.
What should I do if I encounter unexpected behaviour not covered in these docs?
You can ask question in IRC or in the forums.
Check to see if a ticket has been filed in the bug tracker, and if not consider writing one.
What else should I know before I start using the API?
It'd probably be helpful to know:
So you're on version 2 of the API then? What happened to version 1?
The version 1 of the API was designed with the data structure of the original (pre-2011) version of the MusicBrainz database in mind. It was deprecated in 2011 when we changed to our current data schema, and after running (without further updates) for several years to avoid breaking any tools using it, it was finally taken down in 2019.
Do you ever make breaking changes?
We try to avoid that, but sometimes we might need to do so. In those cases, they will be announced on our blog, so consider following that!