In this post we’ll set up a Flask app serving as a starting point for building a REST API. If you know some Python, you will be able to go through the steps below to successfully set up the API on your own. Note: I’m using Python 3.6.3.

The full source code can be found on Github:

What we’ll use:

  • Python 3 and PyCharm as an IDE
  • Zeit Now, a serverless platform
  • Flask, a popular Python micro framework for the web
  • Flask-RESTPlus, a Flask extension for building REST APIs
  • PostgreSQL as a database (hosted remotely on AWS RDS)
  • Psycopg2, the most popular PostgreSQL adapter for Python

The end result is a fully working Flask-powered REST API serving as a starting point for your project (for example, a microservice). As it is hosted on Zeit Now, you’ll be able to deploy it without having to provision any servers.

Preliminary Steps

Be sure that you have signed up for a Zeit account and have installed the command line (an easy way to do that, and automatically set up your local environment with the correct credentials to deploy to Zeit Now, you can download and install the macOS client, „Zeit Desktop“). You’ll have to sign in via the app from the menu bar. Now Desktop comes with Now CLI (the command line interface for Now). We’ll use the Now CLI to deploy our API to Zeit Now.

Step 1: Set up project folder and install Psycopg2

In this step we will install all requirements on our local machine. I’m using macOS 10.14, so the commands that follow might not correspond exactly to your environment. Run the following commands in Terminal:

# setup project folder
cd ~/PycharmProjects
mkdir barebone-serverless-flask-api-zeit-now
cd barebone-serverless-flask-api-zeit-now

# setup virtual environment
python3 -m venv my_virtual_environment
source my_virtual_environment/bin/activate
pip3 install flask flask-restplus Flask-SQLAlchemy psycopg2
pip3 freeze > requirements.txt

# setup project structure and open in PyCharm
touch now.json
charm .

The first step is to configure the deployment settings for Zeit Now. Many thanks for the now-flask builder provided by @liudonghua123! In now.json, add the following:

    "version": 2,
    "name": "barebone-serverless-api-zeit-now",
    "builds": [
        { "src": "*.py", "use": "@liudonghua123/now-flask" , "config": { "maxLambdaSize": "30mb" } }
    "routes": [
        { "src": "/.*", "dest": "/"}

To begin with, we will set up a route /hello_world, which will output a basic „Hello World“ example. In, add the following:

from flask import Flask
from flask_restplus import Resource, Api, fields
from werkzeug.contrib.fixers import ProxyFix

app = Flask(__name__)
app.wsgi_app = ProxyFix(app.wsgi_app)
api = Api(app,
          title='Our sample API',
          description='This is our sample API'

class HelloWorld(Resource):
    def get(self):
        return {'hello': 'world'}

if __name__ == '__main__':

Now, we can test if everything is working properly by running the following command in Terminal (alternatively, we can run it directly from within PyCharm with CTRL+R:


The above command will run a HTTP server for you to debug your code locally. You’ll be able to check if everything is working by navigating to and see the response {"hello": "world"}:

By accessing the root of your API,, you will be presented with a documentation page describing the API (optionally, you can download the Swagger-specifications in json format – more on this later).

You can quit the server with CTRL + C. Deploying the app to Zeit Now requires only one single command. Just run the following command in Terminal while in your project folder:


That’s it! You can check if everything was correctly deployed to Zeit Now by navigating to the endpoint /hello_world of the deployment URL retrieved from Terminal (it is conveniently copied to your clipboard). It should return the identical output {"hello": "world"}, as we’ve already seen in the previous step from testing the API locally.

In the next steps, we will connect our API with a PostgreSQL database, set up an additional endpoint to retrieve data and finish our boilerplate.

Step 2: Database setup

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');

The next step is to download a custom compiled psycopg2 C-library for Python. Using psycopg2 via requirements.txt (conventional approach for installing modules) will not work. We will need to use the library from this GitHub repository. Be sure to download the repository to your machine, and (as we use Python 3) place the folder psycopg2-3.6 at the same level of your now.json file (root project folder). Then, rename the folder so it is called psycopg2. As Zeit Now uses AWS Lambda to deploy your project, we need to use this custom pre-compiled library. Many thanks to Jeff Kehler for pre-compiling and publishing this library!

The next step involves creating a database connector file and a file to define our model classes, as well as setting up the new route in Run the following commands in Terminal to create the additional files:


When testing our project locally, we need to use the regular psycopg2 module, but when deployed, we need to add instructions to load the custom pre-compiled module installed above (note the first try/except clause in the code below). In, add the following code (be sure to modify your database credentials accordingly):
import importlib.machinery
from distutils.sysconfig import get_python_lib
from sqlalchemy import create_engine, MetaData
from sqlalchemy.orm import scoped_session, sessionmaker

# if local environment, use psycopg2 installed in python library (site-packages), otherwise use from binary (psycopg2 subdirectory in this folder)
    psycopg2 = importlib.machinery.SourceFileLoader('psycopg2', get_python_lib()+'/psycopg2/').load_module()
    import psycopg2

username = "xxx"
databasename = "xxx"
host = ""
password = "xxx"

engine = create_engine('postgres://{}:{}@{}/{}'.format(username, password, host, databasename), convert_unicode=True)
metadata = MetaData()
db_session = scoped_session(sessionmaker(autocommit=False,

def init_db():

In, we will reflect our database schema by defining a class called „BlogPost“. Add the following code to the file:

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): = id
        self.title = title = post

blog_posts = Table('blog_posts', metadata,
    Column('id', Integer, primary_key=True),
    Column('title', Text),
    Column('post', Text)

mapper(BlogPost, blog_posts)

Now, we will have to set up the new route /blog_posts in our main file,, by modifying its content to the following code (note the addition of the two import statements):

from flask import Flask
from flask_restplus import Resource, Api, fields
from werkzeug.contrib.fixers import ProxyFix
from database import db_session
from models import BlogPost

app = Flask(__name__)
app.wsgi_app = ProxyFix(app.wsgi_app)
api = Api(app,
          title='Our sample API',
          description='This is our sample API'

class HelloWorld(Resource):
    def get(self):
        return {'hello': 'world'}

class BlogPosts(Resource):
    model = api.model('BlogPost', {
        'id': fields.Integer,
        'title': fields.String,
        'post': fields.String,
    @api.marshal_with(model, envelope='resource')
    def get(self, **kwargs):
        return BlogPost.query.all()

def shutdown_session(exception=None):

if __name__ == '__main__':

You can test if everything is working as expected by running the following command (or, again, directly run it from within PyCharm with CTRL+R:


By navigating to, you can verify if the entries are retrieved as expected from the database and returned in JSON format:

The only step remaining is to deploy the API to Zeit Now in order to expose it to the public.

Step 3: Deploy the API to Zeit Now

Now, all we have to do is to deploy the updated project to Zeit Now. Again, this is extremely convenient and can be done by running the following command in Terminal:


Accessing the endpoint /hello_world of the URL returned by the Now CLI will return the „Hello World“ example, and navigating to the endpoint /blog_posts will return the database entries in JSON format:

You can check the logs by accessing the endpoint /_logs of your deployment URL. This will redirect to the logs accessible on your Zeit account (logs are not public any can only be accessed by you when being logged in to your account).

Note: You can download the Swagger specifications for import to your favorite API Development Environment (for instance, Postman or Paw). This will allow you to test your API more efficiently, especially as soon as it starts to grow when you implement more routes and functionality. In Paw, you can import the swagger.json (located at the root of your project) with CTRL+ALT+⌘+SHIFT+I very easily, allowing you to just paste the URL of your swagger.json file. Be sure to install the import specifications for Swagger 2.0 before importing. After importing, everything is set up automatically:

Congratulations! You’ve now successfully set up a boilerplate serverless Flask-powered JSON API serving as a starting point for your project. You can add more endpoints / routes according to the specifications of your projects. P.S.: You can also clone the GitHub repository to get a head start for your next project, instead of following the steps above – it contains all the files from this tutorial, including the pre-compiled psycopg2 library.

Zeit Now is free up to a certain point – check out their pricing on how it scales as you grow.

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