“long exposure photography of hurricane” by Nikolas Noonan on Unsplash

How to build a REST API in Python with Tornado (part 1)

I’ve been a front-end developer for a pretty long time now and I’ve worked a lot with REST API endpoints before but never knew how to create one. At Octopus Labs we use Python and Tornado to create endpoints, and for my 10% project time I decided to open this black box, and it’s not as difficult as I thought it would be. I decided to create a little tutorial for other frontend people who want to have a go at doing the same or just people who want to learn how to use Tornado.

This tutorial assumes you either have a basic knowledge of Python or some modern Javascript experience.

Main setup

1. Make sure you have a decent text editor, I recommend VScode because of the debugging support and it’s free.

2. Download Postman and install it on your machine, it’s free too. This will be used to check our API is working.

3. Make sure you have Python installed, check by typing

$ python

in the terminal and you should be taken to the Python console.

If not you can download it here. For this tutorial, it doesn’t matter if you have the 2x or 3x version of Python. Exit the console by typing quit().

4. You will need to get pipenv which is the Python equivalent of npm. To download it type this into the terminal.

$ brew install pipenv

Then typing pipenv should show:

5. Create a folder somewhere called todo-list-api and navigate to it.

6. Type:

$ pipenv install tornado

To install Tornado. Once it’s done you should see a Pipfile and Pipfile.lock equivalent to package.json and package-lock.json.

Creating A simple endpoint

1. Inside the todo-list-api folder create a file called app.py.

2. Copy and paste this piece of code (this code will be explained later):

3. Then in your terminal run:

$ pipenv run python app.py

Nothing should happen which is good.

4. Now navigate to http://localhost:3000/ in your browser and if all goes well you should see:

Congratulations, you’ve created an endpoint. 🎉

Now let’s explain what these 15 lines of code are doing, much of it is self-explanatory.

Lines one and two are importing, of course.

The class HelloHandler (lines 4–6) which inherits RequestHandler had a function called get() and that writes a dict (object in JS) to the page as JSON.

The make_app function (lines 8–10) is what deals with the urls and server settings as well as creating the application.

And the last section runs the server.

if __name__ == ‘__main__’:

This piece of code is only for convention, in this case you could take it out and the endpoint will still work fine. Basically Python is saying here run this code only if app.py is run from the terminal. If we made another file called app2.py and ran ‘python app2.py’ instead, the code below if __name__ == ‘__main__’ in app.py will not run.

Postman setup

As we’re not going to be checking endpoints in the browser the whole time let’s setup postman to do it

1. Click on the new collection icon and give it a name of `Tornado todo list`.

2. In New Tab if the dropdown next to the address bar doesn’t say GET change it so it does.

3. Put this in the address bar http://localhost:3000/.

4. Then below that click on the headers tab, add a key of Content-Type and value of application/json.

5. Clicking the blue SEND button should show the relevant response.

6. Last but not least, save this new endpoint in the folder you’ve just created with the request name /items (this will make sense later on).

One endpoint down, 4 more to go :)

At the risk of making this post too long, I will stop here and release the rest as a part 2. The main setup is pretty much complete, from here on we will add a few more endpoints for a little todo list we will create (if you haven’t figured that out already). I hope you’ve learnt something from this and I hope you click on to the next part to learn a bit more.

Go to Part 2 →