Building a RESTful API with Flask - part 0: getting started
Tags: python, webdev, flask, restful
Published: 2020-10-15 06:58:37

There can be some mystique aura surrounding APIs, and REST API is no exception. When I first got started with my current job position, I had no idea what the heck it was, yet had build one myself (with my team, of course). With this article, I hope to demistify this mystery and show that you can build one too!

For the technology stack, we'll have Python 3.7 or above. We'll be building our stuff on top of Flask micro-framework. To test, we'll be using cURL (Windows users, you should have it by now). We'll also need a Linux box running as a production server. There's actually quite a bit more to that, but we'll get to that. As for now, this should be enough.

Let's get started!

# Setting up the environment

If you haven't made a directory for your project, do it now. If you've never done it before, better start doing so now!

For this example, I'll be naming my directory `restful-api`. Let's point our terminal to that and run `python3 -m venv venv` to install the virtual environment. Windows user would wanna run `py -3 -m venv venv` instead. You will now see a new directory called `venv`.

With this virtual environment, you get to install any python packages without touching any of your actual system files. When you're done with it (or somehow mess it up), you can just delete it and create new one when you're ready to use it again. Avoid the temptation to move it around as it won't work (I've learned it the hard way).

Before you do anything, the virtual environment needs to be activated. Unlike what you did above, this one needs to be done **everytime** you open a new terminal to run anything (e.g. when you're getting back from a break). To do so, run `. venv/bin/activate`. Windows user would instead run `venv\Scripts\activate`.

Now, assuming you're already in the virtual environment, you will install the necessary python packages. Run `pip install flask`. Windows user would do the same.

# Creating the App

After the installation finish (or while waiting for it), create a new directory called `app` where you will do most of your work. Create a file called `__init__.py` and fill it with:
```
from flask import Flask

def create_app(config_object=None):
    app = Flask(__name__)

    @app.route('/')
    def hello():
        return 'Hello World!\n'

    return app
```

That's it! You've created a working application.

Check out the [Flask documentation](https://flask.palletsprojects.com/) for more information on how it works.

You actually could've put everything in a single file and make everything much simpler like in many other tutorials. However, this method would make it more manageable when scaling bigger. You can thank me later.

# Testing the App

To test it (after the installation finish), run `flask run`. You can see it in your terminal that the app is now accessible thru `http://127.0.0.1:5000`.

To access this, you can use any HTTP client. Web browser would do for this step (go on, try it!), but not for the next ones as we'd need to manipulate our request data with relative ease.

So we'll use cURL, a command line HTTP client. Now open a new terminal and type `curl http://127.0.0.1:5000` (alternatively, can type `curl localhost:5000`).

You may have been using Postman. If you're already familiar with it, you can use it to test this app.

```
kenno-ideapad:[kenno]:~$ curl localhost:5000
Hello World!kenno-ideapad:[kenno]:~$ curl http://127.0.0.1:5000/
Hello World!kenno-ideapad:[kenno]:~$ 
```

# Touching up

> But wait, shouldn't RESTful API be doing stuff in JSON?

That is true... and I was just showing you how to get things working.

Now to get it working in JSON, we're going to revisit `app/__init__.py`.

Go to the line with `from flask import Flask` and add `, jsonify` at the end, turning it into `from flask import Flask, jsonify`

Now go to the function `hello()` and change its return statement from `return 'Hello World!\n'` to `return jsonify({'message': 'Hello World!'})`.

You will now have on your `app/__init__.py`
```
from flask import Flask, jsonify

def create_app(config_object=None):
    app = Flask(__name__)

    @app.route('/')
    def hello():
        return jsonify({'message': 'Hello World!'})

    return app
```

Restart the application by pressing `Ctrl-C` on the console and running `flask run` again.

Check again with your cURL.

```
kenno-ideapad:[kenno]:~$ curl http://127.0.0.1:5000/
{"message":"Hello World!"}
kenno-ideapad:[kenno]:~$ curl localhost:5000
{"message":"Hello World!"}
kenno-ideapad:[kenno]:~$ 
```

Better?

Stay tuned for the next part! While at it, get your Linux box ready and get it on your home network.