Create a Flask REST API running on AWS Elastic Beanstalk

This post explains how to set up a Flask app serving as a starting point for building a REST API. I’ve compiled the necessary steps to successfully deploy the API via AWS Elastic Beanstalk, including configuration of SSL certificates via Let’s Encrypt.

We’ll use…

• Python 3 and PyCharm as an IDE
• AWS Elastic Beanstalk to host our API
• Flask, a popular Python micro framework for the web
• PostgreSQL as a database (hosted remotely on AWS RDS)
• Let’s Encrypt for SSL encryption
• Gunicorn (WSGI server)

The result is a fully working REST API serving as a starting point for your project (for example, a microservice).

Project Setup and Dependencies

In this step we will install all requirements on our local machine. I’m using macOS 10.12 and Python 3.6 - the commands might not correspond exactly to your environment, so be sure to watch out for that.

# create and go to project folder
cd ~/PycharmProjects/ # cd into your main project folder
mkdir barebone-flask-rest-api
cd barebone-flask-rest-api
# create virtual environment and activate it
python3 -m venv my_virtual_environment
source my_virtual_environment/bin/activate
# within virtual environment, install the following:
pip3 install flask flask-restplus gunicorn psycopg2 Flask-SQLAlchemy
pip3 freeze > requirements.txt
deactivate
# set up file structure
touch app.py wsgi.py database.py models.py

Important: While debugging, when serving the API or when you install additional dependencies below using pip, make sure you switch to the virtual environment accordingly:

source my_virtual_environment/bin/activate # activate virtual environment
# your commands here
pip3 freeze > requirements.txt # after you're done, this will ensure that requirements.txt is up to date
deactivate # this will exit the virtual environment

Open the project folder in your code editor, e.g., VS Code or PyCharm.

To get started, add the following barebone code to create the first route:

from flask import Flask
from flask_restplus import Resource, Api
 
application = Flask(__name__)
api = Api(application,
          version='0.1',
          title='Our sample API',
          description='This is our sample API',
)
 
@api.route('/hello')
class HelloWorld(Resource):
    def get(self):
        return {'hello': 'world'}
 
if __name__ == '__main__':
    application.run(debug=True)

Prepare the WSGI server (we’re using gunicorn):

from app import application
 
if __name__ == "__main__":
    application.run()

You can make sure that everything is working properly by directly executing the Flask app:

# First option: Run with python interpreter (only for debugging)
python3 app.py --debug
# * Running on http://127.0.0.1:5000/
# * Restarting with stat
# * Debugger is active!

Alternatively, run gunicorn to serve your app:

# Second option: Run with gunicorn (used for production later)
gunicorn --bind 0.0.0.0:8080 wsgi:application -w 1
# Starting gunicorn 19.7.1
# Listening at: http://0.0.0.0:8080 (19694)
# Using worker: sync
# Booting worker with pid: 19697

Press CTRL+C to exit the respective process. By default, Flask RestPlus provides Swagger UI documentation, served from the root of the API. After accessing the root URL (see above, for example http://0.0.0.0:8080) from your browser, you’ll be presented with the automatically-generated Swagger UI documentation, in which you can interact with the API (using the “Try it out!” button):

Try Sample API

Try calling the API endpoint from Terminal (make sure to open a separate window in Terminal, in order not to interrupt the current process):

curl http://0.0.0.0:8080/hello

You can see that upon a GET request, our endpoint /hello will output the expected response from app.py, conveniently formatted in JSON:

{ "hello": "world" }

Our API is now working with a minimal “hello world” scenario and we are ready for the next step, where we will implement another endpoint which will communicate with our PostgreSQL database.

Database Integration

Normally, an API needs to perform operations on a database (i.e. create, read, update and delete, see CRUD). That’s why we will connect our API to a database, in our case a remote PostgreSQL database hosted on AWS RDS.

In our PostgreSQL database, we’ll create a simple table called blog_posts for our purposes by running the following SQL code:

CREATE TABLE blog_posts (
   id serial primary key,
   title text,
   post text
);
INSERT INTO blog_posts (title, post) VALUES ('A title', 'Lorem ipsum dolor');
INSERT INTO blog_posts (title, post) VALUES ('Another title', 'Ipsum dolor sit amet');

First, let’s set up database handling:

from sqlalchemy import create_engine, MetaData
from sqlalchemy.orm import scoped_session, sessionmaker
 
engine = create_engine('postgres://your_username:your_password@your_rds_subdomain.rds.amazonaws.com/your_database', convert_unicode=True)
metadata = MetaData()
db_session = scoped_session(sessionmaker(autocommit=False,
                                         autoflush=False,
                                         bind=engine))
 
def init_db():
    metadata.create_all(bind=engine)

Then, let’s set up a model to reflect our database schema:

from sqlalchemy import Table, Column, Integer, Text
from sqlalchemy.orm import mapper
from database import metadata, db_session
 
class BlogPost(object):
    query = db_session.query_property()
    def __init__(self, id=None, title=None, post=None):
        self.id = id
        self.title = title
        self.post = post
 
blog_posts = Table('blog_posts', metadata,
    Column('id', Integer, primary_key=True),
    Column('title', Text),
    Column('post', Text)
)
 
mapper(BlogPost, blog_posts)

In the main Flask app file, we need to add new import statements and an additional method, which will retrieve all blog posts from the table. Change the code accordingly:

from flask import Flask
from flask_restplus import Resource, Api, fields
from database import db_session
from models import BlogPost
 
application = Flask(__name__)
api = Api(application,
          version='0.1',
          title='Our sample API',
          description='This is our sample API',
)
 
@api.route('/hello')
class HelloWorld(Resource):
    def get(self):
        return {'hello': 'world'}
 
@api.route('/blog_posts')
class BlogPosts(Resource):
    model = api.model('Model', {
        'id': fields.Integer,
        'title': fields.String,
        'post': fields.String,
    })
    @api.marshal_with(model, envelope='resource')
    def get(self, **kwargs):
        return BlogPost.query.all()
 
@application.teardown_appcontext
def shutdown_session(exception=None):
    db_session.remove()
 
if __name__ == '__main__':
    application.run(debug=True)

Now, serve the API as before by typing the following command in the console, for example with gunicorn:

gunicorn --bind 0.0.0.0:8080 wsgi:application -w 1

Try sending a request to the endpoint we just created from a separate Terminal window:

curl http://0.0.0.0:8080/blog_posts

You can see that upon a GET request, our endpoint /blog_posts will query the database and return the blog posts in JSON format:

{
  "resource": [
    {
      "id": 1,
      "title": "A title",
      "post": "Lorem ipsum dolor"
    },
    {
      "id": 2,
      "title": "Another title",
      "post": "Ipsum dolor sit amet"
    }
  ]
}

We successfully connected to our database. Let’s proceed to the next step, where we will prepare our app for deployment to AWS Elastic Beanstalk.

Deployment to AWS Elastic Beanstalk

In order to deploy our API to AWS Elastic Beanstalk, we first need to install the AWS Elastic Beanstalk command line interface. I recommend installation using brew, which handles all dependencies correctly. If you have it already installed on your machine, you can skip this step. Run this command in order to install the CLI:

brew install awsebcli

You can check if the installation was successful by executing:

eb --version

Now, execute the following in your project folder to initialize the application and register it with AWS Elastic Beanstalk (be sure to change the region accordingly; below, eu-west-1 is selected):

eb init -p python-3.4 -r eu-west-1 barebone-flask-rest-api

Note: Python 3.4 is the latest version available at the time of writing.

This will trigger prompts which will help you to set up the application. You will need to enter your AWS credentials, namely aws-access-id and aws-secret-key.

In order to install PostgreSQL on the EC2 instances where our API will be deployed, an additional step is required. Paste the following in Terminal to add additional dependency installation instructions to the corresponding file to enable PostgreSQL support in AWS Elastic Beanstalk environments (the file is located at .ebextensions/packages.config):

mkdir .ebextensions
echo "packages:
  yum:
    postgresql94-devel: []" >> .ebextensions/packages.config

The following command will create an environment (called testenv-barebone-flask-rest-api), provision the necessary instance (we’ll use a single instance setup without load balancer) and deploy the application:

eb create testenv-barebone-flask-rest-api --single -i t2.nano
eb use testenv-barebone-flask-rest-api

This will take a few minutes to complete. Note that at this point, the application will not work yet, because the default WSGI-Path configured by AWS Elastic Beanstalk is application.py, whereas in our project it is wsgi.py.

In order to tell AWS Elastic Beanstalk to set up the EC2 instances with the correct WSGI-Path (where our API should ultimately be served from), we have to adjust the configuration:

eb config

Change application.py to wsgi.py (see below). This will ensure that the correct file from our project folder is referenced (in other words, defining wsgi.py as the entry point to our application).

[...]
aws:elasticbeanstalk:container:python:
   NumProcesses: '1'
   NumThreads: '15'
   StaticFiles: /static/=static/
   WSGIPath: wsgi.py # change this from application.py to wsgi.py
[...]

Exit and confirm the changes. This will subsequently deploy the new configuration to your EC2 instance (i.e., replace the current instance).

After deployment of the new configuration (which takes another 2–3 minutes) you can type the following command to open the URL under which your API is served from - and confirm that everything is working as it should:

eb open

You can also retrieve the CNAME (alongside other useful information about your environment) like so:

eb status

You can see that the two methods we’ve implemented are working properly by calling them from your Terminal or browser. Alternatively, you can test the endpoints using a API client like Postman or Paw – especially when implementing more methods this should speed up your development and debugging.

Postman

If you make changes to the source code of your API, you can re-deploy it to AWS Elastic Beanstalk via the following command:

eb deploy

SSL Configuration via Let’s Encrypt

The steps below will show you how to configure an SSL certificate without additional charges, using Let’s Encrypt. First, you’ll need to create a hosted zone for your custom domain in Route 53. Then, you can attach a CNAME Alias in the hosted zone, pointing to your AWS Elastic Beanstalk deployment. See this AWS guide for more information.

Note: The next step will download a config file from gist.github.com. Be sure to check out the source code before pasting the command into your command line!

After you verify that the Route 53 DNS changes have propagated successfully, run the following commands in Terminal in the root of your project (be sure to replace the two environment variables with your email, as well as your domain name configured in Route 53 from the step above):

eb setenv [email protected] LETSENCRYPT_DOMAIN=example.com
mkdir .ebextensions
wget -q https://gist.githubusercontent.com/visini/70c5b11c136be16ea2fe12a6d7b9bf3b/raw/231d3dedf4256b9081e46421714d7f8477055def/elasticbeanstalk-letsencrypt-ssl.config -O .ebextensions/elasticbeanstalk-letsencrypt-ssl.config
eb deploy

The config script above will install a cronjob to make sure that your SSL certificates are periodically renewed. Now, your API is served via AWS Elastic Beanstalk, accessible on your custom domain, and secured via SSL provided by Let’s Encrypt.

I hope you enjoyed this article  -  please let me know if you have any questions or if you run into any issues. Thanks for reading!