API:Etiquette

This page is part of the MediaWiki API documentation.

Language:	English

MediaWiki API

Quick overview:

• Quick start guide
• FAQ
  • Etiquette and usage limits
• Tutorial
• Formats
• Error reporting
• Restricting usage
• Authentication
  • Login
  • Logout
• Queries
  • Meta information
  • Properties
  • Lists
• Search suggestions
• Expanding templates and rendering
• Purging pages' caches
• Parameter information
• Changing wiki content
  • Create and edit pages
  • Move pages
  • Rollback
  • Delete pages
  • Restore deleted revisions
  • (Un)protect pages
  • (Un)block users
  • (Un)watch pages
  • Send e-mail
  • Patrol changes
  • Import pages
  • Change user group membership
  • Upload files
  • User options
• Watchlist feed
• Extensions
• Using the API in MediaWiki and extensions
• Miscellaneous
• Implementation
• Client code

NOTE: This page is a work in progress

Also read the quick start guide. It answers some questions not answered here and points to other useful pages.

Help

1. Read this FAQ.
2. Try to find the answer to your question in the API documentation here or on the self-documenting API home page.
3. If you can't find the answer to your question on the web, you can ask your question on the mediawiki-api mailing list.

Behavior

Request limit

There is no hard and fast limit on read requests, but we ask that you be considerate and try not to take the site down. We also reserve the right to unceremoniously block you if you do endanger the stability of the site.

If you make your requests in series rather than in parallel (i.e. wait for the one request to finish before sending a new request, such that you're never making more than one request at the same time), then you should definitely be fine. Also try to combine things into one request where you can (e.g. use multiple titles in a titles parameter instead of making a new request for each title. Or use "generator" if possible instead of making a request for each result from another request).

Parsing of revisions

While it is possible to query for results from a specific revision number this is an expensive operation for the servers. To retrieve a specific revision use the 'oldid' parameter, example:

• http://en.wikipedia.org/w/api.php?action=parse&format=xml&prop=images&oldid=254862759
• http://en.wikipedia.org/w/api.php?action=parse&format=xml&prop=images&oldid=462841413

Use maxlag parameter

If your task is not interactive (i.e. A user is not waiting for the result) you should use the maxlag parameter. This will prevent your task from running when the load on the servers is high.

See: Manual:Maxlag_parameter

User-agent header

Use a descriptive User-agent header that includes your application's name and potentially your email address if appropriate. Do not simply copy the user-agent of a popular web browser (Unless your api client is a javascript application running through said web browser via AJAX, in which case one cannot modify the user-agent). This ensures that if a problem does arise it is easy to track down where it originates. See API:Quick_start_guide#Identifying_your_client and meta:User-Agent_policy for details.