User:Martyav/Apps/Tutorial

This is a tutorial for building a simple web app that uses the MediaWiki Action API to access data from Wikipedia. If you are confused by the terminology used in this tutorial, consult our glossary for basic definitions.

Programming languages
This app uses a web framework called Flask. It allows us to write our Action API requests in Python.

There is also some template code, written in HTML, for automatically generating a web page based on the results from our request. There is an accompanying CSS file for styling the web page.

Finally, there is some Javascript code handling user interactions, such as sending the GET request once the user clicks a button, and dynamically updating the results.

Setting up Python
This tutorial uses Python 3.

You can check if you have Python already installed by opening up a command line application, such as Mac's Terminal, and typing. On machines that already have Python, this command will show you which version is installed. Machines that don't have it will show an error.

If your version of Python is earlier than 3, you will still have to install Python 3. Installing it shouldn't overwrite or remove any earlier versions, and you'll still be able to use them to run older software.

In most cases, having multiple versions of Python won't cause any conflicts, though you may need to specify the version you want when running scripts.

See Can I install Python 3.x and 2.x on the same Windows computer, Switch between python 2.7 and python 3.5 on Mac OS X, and Install and run Python 3 at the same time as Python 2 (Ubuntu Linux) for your respective operating system.

If you don't yet have Python installed, the official Python wiki has a complete beginner's guide on installation for Windows, Mac, and several Linux distros.

You can download the latest Python version from here:


 * Python for Windows 7, 8, and 10
 * Python for Mac OS X

If your operating system is Windows XP, a Linux distro, or something else, see the beginner's guide for further instructions.

Setting up Flask
There is a tool called pip, which should have come with your Python installation. You can check by typing  into your command line interface. Pip lets us easily download and install the Python libraries and frameworks we need.

If you don't have it already, see Pip installation on the official website.

With Pip installed, all you need to do is type  into your command line to get the latest version of Flask.

Hello world
Create a new directory for your app, named PLACEHOLDER_NAME.

Open your new directory and create a new file, named.

To this new file, add the following:

Save the file, and type  into your command line application. This will start a local server, running the code you've just written. You can view the web page in your browser by visiting http://localhost:5000

If Flask is successfully installed, you should see the following:

img of hello world

Making the API query
Now that we have everything set up and know Flask is working, we can start writing our code for hitting the Action API.

Import Requests
The Action API works by sending back data in response to a HTTP request. Since making HTTP requests is so important to the key functionality of our app, we should import the Python Requests library, as it will make our lives easier.

Add the following line to the top of your app.py file:

If you don't already have the library installed, make sure to run the following command in your command line application:

The basic GET request structure
Now, remove the old function,, and add this in its place:

The call to SESSION.get adds the key-value pairs inside PARAMETERS to the end of the ENDPOINT string, placing ampersands in between each key-value pair, equals signs between each key and value, and using percent encoding to automatically handle any spaces. This creates a query that looks like this:

SESSION.get sends the query immediately. If it succeeds, we get back the data we wanted, inside RESPONSE. If it fails, we usually get an error message within the response, though in some cases, it may fail silently -- for example, if we try to do something without having the proper permissions.

Functions making GET requests to the Action API have a fairly regular structure. This code is only missing one thing: the particular API we are trying to hit.

Props & lists
The Action API is made up of numerous smaller APIs, or modules; we will use the two terms interchangeably for the remainder of this tutorial.

For GET requests within the Action API, these smaller APIs generally fall into two broad categories: props and lists.

In many cases, prop modules are used for accessing data within a single page, while list modules are used for accessing data across an entire wiki; however, there is some overlap. The main difference is how they structure the data they return, within the response.

Prop modules return 000, while list modules return 000.

Both props and lists have limits on the amount of data they can return in one go. The default limit for most modules is 10 items. You can see more data by making additional requests with 111.

To make a GET request hit the particular API you want, add  or   to PARAMETERS.

Displaying the page
We have our code for hitting the API, but we don't have much of a web page. It looks very plain, and we can only make a request when we open or refresh the page.

We want to add some code to display results on the page in a fairly stylish and friendly way, as well as add a little user interaction and some dynamic elements, so the user can make different requests without having to refresh the page each time.

Sample app
A complete version of this app is available on Github, at ___.