API:Tutorial

=Tutorial for MediaWiki's RESTful web service API=

Definitions
There are other things that also get casually called the MediaWiki API, like the internal interfaces that extensions and special pages can hook into. We're not talking about that right now, just the web API. (possibly how it works if people asks)
 * REST API for MediaWiki
 * exposes things MediaWiki has in the database or otherwise understands
 * does not include semantic stuff like "definition of a word in Wiktionary" or even "lead paragraph of an article"
 * usage: send HTTP requests (GET or POST) to the api.php URL, receive XML or JSON or other formats. You'll usually want JSON or XML.

How to use it
Follow along by using https://en.wikipedia.org/wiki/Special:ApiSandbox -- query is what you will usually want.
 * Entry point: http://en.wikipedia.org/w/api.php
 * or any other wiki
 * https works too!
 * Parameters are passed in query string. Not passing any --> help page
 * Example query: ?action=query&titles=San_Francisco&prop=images&imlimit=20&format=jsonfm
 * action=query is used for most read actions, separate action= modules exist for write actions
 * titles= takes one or more titles for the query to operate on
 * prop=images lists the images on a page; lots of other stuff in prop=, list=, meta=
 * limit= sets the max # of results. Default is 10, 'max' works
 * popular values for format= : xml, json, xmlfm (default), jsonfm
 * State-changing actions (e.g. editing)
 * POST requests only
 * two-step process involving token
 * details of individual actions are complex, read the docs
 * example: ?action=query&titles=Foo&prop=info&intoken=edit for obtaining edit token, then POST to  ?action=edit&title=Foo&...

Magic recipes
Nonobvious and very useful.
 * prop=info for basic page info
 * prop=revisions for page history
 * prop=revisions&rvprop=content for page wikitext
 * action=parse for page HTML
 * Doing crazy stuff
 * multiple titles with titles=Foo|Bar|Baz
 * multiple modules with &prop=images|templates&list=allpages|blocks
 * generators (kind of like UNIX pipes) with &titles=Foo&generator=links&prop=revisions

Resources

 * Getting help
 * Autogenerated documentation: api.php with no parameters
 * Documentation on mediawiki.org: https://www.mediawiki.org/wiki/API:Main_page (details about specific modules/parameters often outdated, autogenerated docs are authoritative)
 * The API Query Sandbox -- example https://en.wikipedia.org/wiki/Special:ApiSandbox
 * mediawiki-api@lists.wikimedia.org
 * #mediawiki on irc.freenode.net
 * me! (Roan Kattouw)