MusicBrainz API/Rate Limiting

From MusicBrainz Wiki
< MusicBrainz API
Revision as of 00:17, 23 December 2011 by Djce (talk | contribs)
Jump to navigationJump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Introduction

MusicBrainz has finite resources and wishes to make the MusicBrainz database available to as much of the Internet community as possible. However, at certain times of day the number of requests on XML_Web_Service exceeds our capacity for handling these requests. Honoring all of these requests would overload our servers and degrade the service for everyone. For this reason we rate limit our Web Service, which limits the number of requests that clients can make in a given period of time.

When a request reaches our servers we check three conditions, in the following order:

  1. Source IP address: If a single IP address is making one request per second, the requests are all honored. If an IP address goes above 10 requests in 10 seconds, we instantly block that IP address and all requests from that IP address get a 503 error when making further requests. As soon as enough time passes such that the request rate for that IP drops below 10 in the last 10 seconds, requests are honored again.
  2. Global rate limit: If the total number of requests coming in to MusicBrainz exceeds our global rate limit in 10 seconds, all requests are rejected with a 503 error. This continues until the total count of requests in the last 10 seconds drops below the global rate limit. The current rate limit is set at 2,500 requests per 10 seconds. (equivalent to 250 requests per second)
  3. User-Agent string: Each application making requests to our web service must identify itself using the User-Agent string in the HTTP request header. If your application provides no User-Agent string, we will reject the request with a 403 Forbidden error. We have also blocked very common User-Agent strings from generic HTTP request libraries (see below for details). Some applications that use our own client libraries are making too many requests in certain times of the day, which has forced us to block these applications. Soon we're going to throttle some User-Agent strings, rather than blocking them.

We may change the blocking/throttling rules at any time in order to protect the overall site health.

Current blocking rules

As of 2011-12-22 our blocking rules are:

  • User-Agent "python-musicbrainz/0.7.3": throttled to 500 requests per 10 seconds
  • Other "anonymous" User-Agents: collectively throttled to 500 requests per 10 seconds

By "anonymous" we mean any request whose User Agent header provides insufficient information to identify the originating application. In practice we allow all User-Agents by default, and only blacklist some as "anonymous". Specifically, the ones that are currently flagged as anonymous are:

User-Agent String Version
<blank> -
Java any
Python-urllib any
Jakarta Commons-HttpClient any

All of the above User-Agent throttling is done _before_ the usual IP / global rate-limiting. So for example even if your request is not denied based on User-Agent throttling, it may still be denied based on per-IP throttling.

Providing meaningful User-Agent strings

To be a good citizen in the MusicBrainz world, please provide a User-Agent string which clearly identifies your application. We suggest that your User-Agent string should look like:

Application name/<version> ( contact-url )

or

Application name/<version> ( contact-email )

two examples:

MyAwesomeTagger/1.2.0 ( http://myawesometagger.example.com )
MyAwesomeTagger/1.2.0 ( me@example.com )

What can I do if my application is blocked?

If you are an application author and your application has been blocked, you will need to change your application to send us an identifiable User-Agent string. See the section above on how to do this. If you have a good User-Agent string and your application has been blocked, you should contact us to find out why we blocked you.

Our client libraries now support functions for setting the User-Agent string. If you are using one of our libraries, you will need to add a call to set the User-Agent string via the library and your application should work again.

How can I be a good citizen and be smart about using the Web Service?

Please refrain from having your applications wake up at a certain time of the day to perform some action. For instance, having your application wake up at 03:00 local time and query a lot of data at MusicBrainz is a bad idea. If this application gets distributed to many users around the globe (e.g. in a Linux distribution), then at various times around the clock, but always at the beginning of the hour, MusicBrainz will be overloaded with requests from your application. Also, 03:00 in your timezone might be the peak time for MusicBrainz somewhere else in the world. If you program your application this way and it impacts our service, we will block your application.

If there is a task you would like to perform in the background and are tempted to do it at an off-peak time, you should have your application make calls at random intervals throughout the day. If the application spreads its calls throughout the day, it spreads the load on the MusicBrainz servers across the day as well and avoids creating artificial peak times.

Also, if you want your application to poll MusicBrainz to see if some metadata has changed, please don't do this. Metadata really doesn't change all that often and therefore polling for changes will rarely give good results. We currently do not have a good solution in place to let users know when metadata does change, but it is something we would like to address in the future.