API:Quick start guide

This page contains some must-read information for anyone using the API.

Recommended reading
It is recommended that you read the following parts of the manual:


 * The rest of this page
 * The FAQ
 * The page about input and output formats
 * The page about errors and warnings
 * The page about logging in if you need to log in as a certain user
 * The manual pages for the modules you want to use. You can use the right-hand menu to locate them
 * Our Terms of use (if you are accessing a Wikimedia Foundation wiki) and any policies that apply to the wiki you want to access - these apply to you when you access or edit using the API just as much as if you do it by hand.

What you need to access the API
The MediaWiki API is based around HTTP calls to an endpoint. This endpoint for most MediaWiki installations is located at:

http://www.example.com/w/api.php

For example, the API endpoint for this wiki is located at:

http://www.mediawiki.org/w/api.php

All Wikimedia projects, such as Wikipedia follow the same path structure, e.g.

http://en.wikipedia.org/w/api.php     # English Wikipedia API http://nl.wikipedia.org/w/api.php     # Dutch Wikipedia API http://commons.wikimedia.org/w/api.php # Wikimedia Commons API

See also How do I call the API?

There are client libraries specifically for this API, or you can write your own using a generic HTTP library.

Identifying your client
Pass a  header that properly identifies your client: don't use the default   from your client library, but use a custom one including the name of your client and the version number, something like.

On Wikimedia wikis, failing to supply a  header or supplying an empty or generic one will cause the request to fail with an HTTP 403 error. See User-Agent policy. Other MediaWiki wikis may have similar policies.

If you are calling the API from browser-based JavaScript, you won't be able to influence the  header: the browser will use its own; there is currently no other mechanism for clients to identify themselves.

Logging in
Your client will need to log in if:


 * it needs to obtain information or carry out an action that is restricted to users with certain rights
 * it is making large queries that would be inefficient without the higher per-request limits reserved for accounts with certain rights

On private wikis, logging in is required to use any API functionality.

While it is possible to edit through the API without logging in on wikis that allow anonymous editing, it is highly recommended to log in.

If your application is carrying out automated editing or some other bulk operation, or making many/rapid large queries, you are advised to use a separate user account created specifically for that purpose. This allows the changes to be easily tracked and special rights (usually a "bot" user group) to be applied. Some wikis have a policy related to automated editing, and/or a procedure for dealing with "bot" user group requests.

For the technical details concerning logging in, see the login manual page.

If your client is in JavaScript, it'll usually act as the user running it. In this case, you won't need to login, as it'll automatically assume the credentials of the user using it, provided they're logged in.

Making your requests cacheable
If your requests obtain cacheable data, you should take steps to make them cacheable so the same data won't be requested over and over again. Some clients may be able to cache data themselves, but for others (particularly JavaScript clients), this is not possible.

Per the HTTP specification, POST requests cannot be cached. Therefore, use GET for all requests intended to be cacheable (when possible, see the API:FAQ). Also note that a request cannot be served from cache unless the URL is exactly the same.

URL construction
When the input is dependent on user input or otherwise variable sources (such as recent changes), one can construct a request in such a way that if the request is different but the same data is needed, the URL will be the same. For example if you're requesting properties of certain titles: This way if slightly different input is given but the same data is needed the url will be same (rather than requesting  and later  ) this way you're more likely to cache results and actually use the cache.
 * Remove duplicates
 * Sort them alphabetically

Resources
Hook into Wikipedia information using PHP and the MediaWiki API (17 May 2011)