In this post you’ll learn how to set up a boilerplate serverless JSON API serving as a starting point for your project. We’ll use Python 3. If you know some Python, you will be able to go through the steps below to successfully set up the project. Note: I’m using Python 3.6.3.

The full source code can be found on Github: https://github.com/visini/barebone-serverless-api-zeit-now

What we’ll use:

  • Zeit Now, a serverless platform
  • Python 3 and PyCharm as an IDE
  • PostgreSQL and psycopg2, the most popular PostgreSQL adapter for Python

The end result is a fully working Serverless JSON API serving as a starting point for your project (for instance, hosting your Python microservices 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:

cd ~/PycharmProjects
mkdir barebone-serverless-api-zeit-now
cd barebone-serverless-api-zeit-now
touch now.json index.py debugserver.py
charm .

The first step is to configure the deployment settings for Zeit Now. We’ll use In now.json, add the following:

{
    "version": 2,
    "name": "barebone-serverless-api-zeit-now",
    "builds": [
        { "src": "*.py", "use": "@now/python" , "config": { "maxLambdaSize": "10mb" } }
    ]
}

We’ll include an entry point to our API (at the default route, /). It will output a basic „Hello World“ example. In index.py, add the following:

from http.server import BaseHTTPRequestHandler
import debugserver
import json

class handler(BaseHTTPRequestHandler):

    def do_GET(self):

        self.send_response(200)
        self.send_header("Content-type", "application/json")
        self.end_headers()

        response = {"hello": "world"}
        self.wfile.write(json.dumps(response).encode("utf-8"))

        return

if __name__ == '__main__':
    debugserver.serve(handler)

In order to test our project locally before deploying to Zeit Now we have to create a custom server to expose our API locally. This enables us to test a specific route of our API via http://localhost:8888 to make sure everything is working as expected before deployment. Add the following in debugserver.py:

from http.server import HTTPServer
def serve(handler):
    try:
        port = 8888
        debugserver = HTTPServer(('', port), handler)
        print('Started httpserver on port', port)
        print('http://localhost:' + str(port))
        debugserver.serve_forever()
    except KeyboardInterrupt:
        print('^C received, shutting down the web server')
        debugserver.socket.close()

Now, we can test if everything is working properly by running the following command in Terminal:

python3 index.py

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 http://localhost:8888 and see the response {"hello": "world"}:

You can quit the server with CTRL + C. Deploying the app to Zeit Now takes mere seconds. Just run the following command in Terminal in your project folder.

now

That’s it! As you can see, the deployment only took 16 seconds:

You can check if everything was correctly deployed to Zeit Now by navigating to the URL you can retrieve from Terminal (it is automatically copied to your clipboard). It should give the identical output {"hello": "world"}, as already seen in the previous step.

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’s 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 this awesome library!

The next step involves creating a database connector file, database.py, and setting up the new route in blog_posts.py. Run the following commands in Terminal to create the additional files:

touch database.py blog_posts.py

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 database.py, add the following code (be sure to modify your database credentials accordingly):

import importlib.machinery
from distutils.sysconfig import get_python_lib

try:
    psycopg2 = importlib.machinery.SourceFileLoader('psycopg2', get_python_lib()+'/psycopg2/__init__.py').load_module()
except:
    import psycopg2

# connect to database
def connect():
    dbname = "xxx"
    user = "xxx"
    host = "xxx.eu-west-1.rds.amazonaws.com"
    password = "xxx"
    try:
        return psycopg2.connect("dbname='{}' user='{}' host='{}' password='{}'".format(dbname, user, host, password))
    except:
        print("I am unable to connect to the database")

Now we will create an endpoint which will retrieve all blogposts from the database. In blog_posts.py, add the following code:

from http.server import BaseHTTPRequestHandler
import json
import database
import debugserver

class handler(BaseHTTPRequestHandler):

    def do_GET(self):

        conn = database.connect()

        self.send_response(200)
        self.send_header("Content-type", "application/json")
        self.end_headers()

        cur = conn.cursor()
        cur.execute("""SELECT * from blog_posts""")
        columns = ('id', 'title', 'post')
        results = []
        for row in cur.fetchall():
            results.append(dict(zip(columns, row)))

        self.wfile.write(json.dumps(results).encode("utf-8"))

        return

if __name__ == '__main__':
    debugserver.serve(handler)

You can test if everything is working as expected by running the following command (this will launch the debug HTTP server):

python3 blog_posts.py

By navigating to http://localhost:8888, you can verify if the entries of the database are retrieved as expected:

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

Because we have added a new route (as defined in the file blog_posts.py), we need to reflect this change in our now.json file, mapping the route endpoint to the python file. Edit the file so it contains the following code:

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

Now, all we have to do is to deploy the updated project to Zeit Now. Again, this only takes a few seconds, and can be done by running the following command in Terminal:

now

Now, accessing the URL returned by the Now CLI will return the „Hello World“ example (as defined in index.py), navigating to /blog_posts will return the database entries in JSON format:

You can check logs by accessing /_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).

Congratulations! You’ve now successfully set up a boilerplate serverless 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!