|This page is part of the MediaWiki Action API documentation.|
|This page in a nutshell:
This page contains the best practices that should be followed when using the API.
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.
Making your requests in series rather than in parallel, by waiting for one request to finish before sending a new request, should result in a safe request rate. It is also recommended that you ask for multiple items in one request by:
- Using the pipe character (
|) whenever possible e.g.
titles=PageA|PageB|PageC, 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
Accept-Encoding: gzipto reduce bandwidth usage.
Requests which make edits, modify state or otherwise are not read-only requests, are subject to rate limiting. The exact rate limit being applied might depend on the type of action, your user rights and the configuration of the website you are making the request to. The limits that apply to you can be determined by accessing the action=query&meta=userinfo&uiprop=ratelimits API endpoint.
When you hit the request rate limit you will receive a API error response with the error code
ratelimited. When you encounter this error, you may retry that request, however you should increase the time between subsequent requests. A common strategy for this is Exponential backoff.
Parsing of revisions
While it is possible to query for results from a specific revision number using the
revid parameter, this is an expensive operation for the servers.
To retrieve a specific revision use the
oldid 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
The value of the
maxlag parameter should be an integer number of seconds.
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 Manual:Maxlag parameter for more details.
The User-Agent header
It is best practice to set a descriptive User Agent header.
To do so, use
User-Agent: clientname/version (contact information e.g. username, email) framework/version....
For example in PHP:
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');
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.
User-Agent header, depending on the browser.
To work around this, use the
See m:User-Agent_policy for more details.
Downloading data in bulk is not always extremely efficient using the Action API. On Wikimedia wikis, there are faster ways to get data in bulk, see m:Research:Data and wikitech:Portal:Data Services for more details.
Per the HTTP specification, POST requests cannot be cached. Therefore, whenever you're reading data from the web service API, you should use GET requests, not POST.
Also note that a request cannot be served from cache unless the URL is exactly the same.
If you make a request for
api.php?....titles=Foo|Bar|Hello, and cache the result, then a request for
api.php?....titles=Hello|Bar|Hello|Foo will not go through the cache — even though MediaWiki returns the same data!
You should take care to normalize the URLs you send to the MediaWiki web service, so that slightly different user input won't cause you to waste time on unnecessary HTTP requests. You can normalize a list of page titles by removing duplicates and sorting the titles alphabetically. Similar techniques will work for other kinds of data.
- API:Main page - The quick start guide.
|This page or project is maintained by Core Platform Team.