API:Tutorial

Language:	English  • 日本語

Play media

An introduction to the API by Roan Kattouw at the San Francisco Hackathon January 2012. This tutorial guide goes along with the video.

This page contains the notes used to present Roan Kattouw's 2012 workshop on the MediaWiki web API and is not a complete tutorial on the MediaWiki web API by any means. It provides a quick introduction to the API, useful recipes for common GET requests, and a list of available resources with more information.

---

This page is part of the MediaWiki action API documentation.

MediaWiki APIsAPI:Main page

• Web APIs showcaseAPI:Web APIs hub
• REST content API

MediaWiki action API

• Introduction and quick startAPI:Main page
• FAQAPI:FAQ
  • Etiquette and usage limitsAPI:Etiquette
• TutorialAPI:Tutorial
• FormatsAPI:Data formats
• Error reportingAPI:Errors and warnings
• Restricting usageAPI:Restricting API usage
• Cross-site requestsAPI:Cross-site requests
• Authentication
  • LoginAPI:Login
  • LogoutAPI:Logout
  • Account creationAPI:Account creation
• QueriesAPI:Query
  • Meta informationAPI:Meta
  • PropertiesAPI:Properties
  • ListsAPI:Lists
• Searching (by title, content, coordinates...)API:Search and discovery
• Parsing wikitext and expanding templatesAPI:Parsing wikitext
• Purging pages' cachesAPI:Purge
• Parameter informationAPI:Parameter information
• Changing wiki contentAPI:Changing wiki content
  • Create and edit pagesAPI:Edit
  • Move pagesAPI:Move
  • RollbackAPI:Rollback
  • Delete pagesAPI:Delete
  • Restore deleted revisionsAPI:Undelete
  • (Un)protect pagesAPI:Protect
  • (Un)block usersAPI:Block
  • (Un)watch pagesAPI:Watch
  • Mark revisions of watched pages as visitedAPI:SetNotificationTimestamp
  • Send emailAPI:Email
  • Patrol changesAPI:Patrol
  • Import pagesAPI:Import
  • Change user group membershipAPI:User group membership
  • Upload filesAPI:Upload
  • User optionsAPI:Options
  • TokensAPI:Tokens
  • Page languageAPI:PageLanguage
• Watchlist feedAPI:Watchlist feed
• WikidataWikibase/API
• ExtensionsAPI:Extensions
• Using the API in MediaWiki and extensionsAPI:Calling internally
• MiscellaneousAPI:Other services
• ImplementationAPI:Implementation Strategy
  • LocalisationAPI:Localisation
• Client codeAPI:Client code
• AssertingAPI:Assert

Tutorial for MediaWiki's RESTful web service API

Why should you use the web API? Bots, AJAX, Gadgets, other things.

Roan says: generally any Ajax feature is going to use the api.php entry point. But right now the easiest thing to do is to write a bot or to use the API clients.

Definitions

• 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.
    • w:en:JSON and w:en:XML and w:en:Representational state transfer (RESTful)

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 talk about how it works from the back end, if people ask)...

How to use it

• Entry point: https://en.wikipedia.org/w/api.php (see API:Main page#The endpoint)
  • or any other wiki
    • Talk about versioning and how non-WMF wikis might have different version of MediaWiki and thus the API
  • https works too!
• Parameters are passed in query string. Not passing any will give you the help page with the autogenerated documentation.

Follow along by using w:en:Special:ApiSandbox – you will mostly use the query Action.

• Here is an example query:

api.php?action=query&titles=San_Francisco&prop=images&imlimit=20&format=jsonfm [try in ApiSandbox]

• • 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=
  • imlimit= sets the max # of results. Default is 10, 'max' works
  • popular values for format= : xml, json, xmlfm (default), jsonfm
  • If you want to find sections from the table of contents, use section= using the index property; you can use section=0 for the wikitext that comes before the first section header.

• 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&...

If you want to make a lot of API calls, and perhaps run very busy and active bots et al., please talk to the admins of that wiki ahead of time so they do not block you. Also run your requests in serial, not parallel. resource for contacting them to go here. TODO

• There are limits in the software on how many edits per second you can make.

• Example nouns to look up:

Kanichar

Kolar_Gold_Fields

Cooperative_principle

MS_Riverdance

Magic recipes

Nonobvious and very useful (these may be outdated - 12/2014)

• Things you'll definitely need:
  • 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 (This will make multiple calls count as one for the purpose of rate limiting)
    • This works for pages but not revisions. Read the documentation via the Sandbox or via api.php autodocs.
  • 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 such as https://en.wikipedia.org/w/api.php, or equivalently visit Special:ApiHelp
  • Documentation on mediawiki.org: API:Main page (details about specific modules/parameters is often outdated, autogenerated docs are authoritative)
  • The API Sandbox -- example w:en:Special:ApiSandbox
  • mail:mediawiki-api -- mediawiki-api@lists.wikimedia.org
  • mediawiki-api-announce@lists.wikimedia.org - PLEASE subscribe because we tell you about breaking changes, which happen a few times every year. mail:mediawiki-api-announce
  • #mediawiki^connect IRC channel
  • me! (Roan Kattouw)

You may actually want

• The dumps of all of Wikipedia so you can work with them locally - http://dumps.wikimedia.org/
• Offline Wikipedia readers such as Kiwix http://www.kiwix.org