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

What you need to access the API
You can access the API by sending HTTP requests to the wiki's. This is located in the same place as ; check the page source if the wiki uses pretty URLs. For example, the API for this wiki is at http://www.mediawiki.org/w/api.php.

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.