API:Quick start guide

NOTE: This page is work in progress

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 api.php, see also the API:FAQ. Therefore, you'll need a library for sending HTTP requests. There are client libraries specifically for this API (list).

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. If you pass a generic, it may be blacklisted and you'll get HTTP 403 errors when using it to call the API on Wikimedia wikis. The same happens when you pass an empty  or don't pass one at all.

If your client is in JavaScript, you won't be able to influence the  header: the browser will use its own. There is currently no mechanism for JavaScript clients to identify themselves, but there will be one in the future.

Logging in
Your client will need to log in if: You will usually log in as a separate user created specifically for your client. Permission to create such a user and have special rights assigned to it (the "bot flag") can be requested on the wiki in question. For the technical details concerning logging in, see the login manual page.
 * it needs to obtain information that's restricted to users with certain rights (on private wikis, this is all information)
 * it needs to use the higher per-request limits reserved for users with certain rights
 * it needs to change information on the wiki, e.g. edit pages (not always required, but recommended)

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.