API:Etiquette - MediaWiki
Jump to content
From mediawiki.org
Translate this page
Languages:
Bahasa Indonesia
Deutsch (Sie-Form)
Hausa
Türkçe
italiano
polski
português
português do Brasil
čeština
кыргызча
русский
українська
עברית
کوردی
ไทย
中文
한국어
This page is part of the
MediaWiki Action API
documentation.
MediaWiki Action API
Basics
Etiquette and usage guidelines
All query modules
All page properties
All list modules
All meta modules
Output formats
Authentication
Get tokens for data modifying operations
Logout
Verifying authentication (assertions)
Accounts and Users
Create an account
Block or unblock a user
Get info about the current user
Get the current user's watchlist as a feed
Change user options
Change user group membership
Send an email
Page Operations
Create and edit a page
Get the contents of a page
Upload a file
Import a page
Delete a page
Parse content of a page
Watch or unwatch a page
Purge cache for page(s)
Rollback a page
Move a page
Patrol a page or revision
Restore revisions of a deleted page
Change a page's protection level
Change a page's language
More...
Search wiki pages by title (OpenSearch)
Advanced search for wiki pages by title or text
Search wiki pages near a location
Search for a language name
Perform a prefix search for page titles
Developer Utilities
Access libraries
Cross-site requests
Creating an API module in an extension
Using the API in MediaWiki and extensions
Restricting API usage
Localisation
Implementation Strategy
Tutorials
Action API Tutorial
Article ideas generator
Nearby places viewer
Picture of the day viewer
Holidays viewer
This page in a nutshell:
Set an informative User-Agent string with contact information, or you may be IP-blocked without notice.
Make your requests in series rather than in parallel, by waiting for one request to finish before sending a new request.
Perform grouped updates via one single
editEntity
, for all languages and for labels, descriptions, and aliases at once.
This page contains the best practices that should be followed when using the Action API.
Behaviour
Request limit
There is no hard speed 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: gzip
to 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.
api.php
action=query
format=json
meta=userinfo
uiprop=ratelimits
[try in ApiSandbox]
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:
api.php
action=parse
format=json
prop=images
oldid=254862759
[try in ApiSandbox]
The maxlag parameter
If your task is not interactive, i.e. a user is not waiting for the result, you should use the
maxlag
parameter.
The value of the
maxlag
parameter should be an integer number of seconds.
For example:
api.php
action=query
format=json
titles=Main%20Page
maxlag=1
[try in ApiSandbox]
This will prevent your task from running when the load on the servers is high.
Higher values mean more aggressive behaviour, 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.
If you are calling the API from browser-based JavaScript, you may not be able to influence the
User-Agent
header, depending on the browser.
To work around this, use the
Api-User-Agent
header.
Data formats
All new API users
should use JSON
See
API:Data formats
for more details.
Caching
If your requests obtain data that can be cached for a while, you should take steps to cache it, so you don't request the same data over and over again.
Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.
POST requests
Whenever you're reading data from the web service API, you should try to use GET requests if possible, not POST, as the latter are not cacheable and, in
multi-datacenter
configurations (including Wikimedia sites), may go to a farther data center.
In exceptional cases where you really need to use POST for a read request, such as calling
action=parse
with a long string of wikitext, consider setting the
Promise-Non-Write-API-Action: true
header.
This helps ensure that your POST request is processed by an application server in the closest data center, if appropriate.
There is no need to set this header for GET requests, and neither should it be set when making
cross-wiki requests
within a wiki family using CentralAuth; see
T91820
Guidelines for Wikimedia wikis
In addition to the best practices described above, the following guidelines apply to using the Action API to access Wikimedia wikis.
See also
the official guidelines about API usage
on Wikimedia Foundation Governance wiki.
User-Agent policy
API requests to Wikimedia wikis must include a meaningful User-Agent header.
See
User-Agent policy
for more details.
Rate limits
In addition to
rate limits
based on user actions, API requests to Wikimedia wiki are subject to
API rate limits
Performance
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.
See also
Official guidelines about API usage
on Wikimedia Foundation Governance wiki
Wikimedia Robot policy
on Wikitech
API:Main page
- The quick start guide.
Manual:Rate limits
Wikimedia APIs/Rate limits
Code stewardship
Maintained by
MediaWiki Interfaces Team
Live chat (
IRC
):
#mediawiki-core
connect
Issue tracker:
Phabricator MediaWiki-Action-API
Report an issue
Retrieved from "
Category
MediaWiki action API
API
Etiquette
Add topic