API:Etiquette

This page contains the best practices that should be followed when using the API.

Request limit
There is no hard and fast limit on read requests, but be considerate and try not to take a site down.

Most system administrators reserve the right to unceremoniously block you if you do endanger the stability of their site.

It is okay to make your requests in series rather than in parallel by waiting for one request to finish before sending a new request. However, it is recommended that you ask for multiple items in one request by:
 * Using the pipe character whenever possible e.g , instead of making a new request for each title.
 * Using a generator instead of making a request for each result from another request.

Use GZip compression when making API calls by setting  to reduce bandwidth usage.

Parsing of revisions
While it is possible to query for results from a specific revision number using the  parameter, this is an expensive operation for the servers.

To retrieve a specific revision use the  parameter. For example:

The maxlag parameter
If your task is not interactive, i.e. a user is not waiting for the result, you should use the  parameter. The value of the  parameter should be an integer number of seconds. For example:

This will prevent your task from running when the load on the servers is high.

Higher values mean more aggressive behavior, lower values are nicer.

See for more details.

The User-Agent header
It is best practice to set a descriptive User Agent header. To do so, use. For example in PHP:

Do not simply copy the user-agent of a popular web browser.

This ensures that if a problem does arise it is easy to track down where it originates.

If you are calling the API from browser-based JavaScript, you may not be able to influence the  header, depending on the browser. To work around this, use the  header.

See User-Agent_policy for more details.

Data formats
All new API users should use JSON. See for more details.

Performance
If you are getting results more slowly than you would like, read the  to help you think about performance generally.

If reading via the API rather than directly reading from databases is impeding your client's performance, consider whether to [http://tools.wmflabs.org/ put it into Wikimedia's Toolforge].