Introduction

RESTful APIs are a major component of any well-architected stack, and Python happens to have some brilliant frameworks for quickly composing APIs.

One of these frameworks is called Falcon - and it’s great! Essentially a microframework, it ships with a sizable number of advantages:

  1. It’s fast. Really fast. Check out the benchmarks here.
  2. HTTP Resources are defined as classes, with class methods being used for different REST operations on these resources. This helps maintaining a clean codebase.
  3. It’s quite extensible - check out this section on their wiki, to get a feel for it.
  4. It’s based on WSGI - the Pythonic standard for web apps - so it works with Python 2.6, 2.7, and 3.3+. And if you need more performance, run it using PyPy!

Getting started

First, let’s prepare our environment. Personally, it’s always great to work in virtual environments - you can use virtualenv, virtualenvwrapper or venv. Next, install Falcon using pip: pip install falcon.

We’re going to develop a small sample API that does very basic time-zone manipulations for us. It will display the current time in UTC, as well as the corresponding epoch time. To that end, we’ll grab a nifty library called arrow: pip install arrow.

You can find the finished sample at https://github.com/rudimk/freecodecamp-guides-rest-api-falcon.

Resources

Think of a resource as an entity that your API needs to manipulate. In our case, the best resource would be a Timestamp. Our routing would typically be something like this:

GET /timestamp

Here, GET is the HTTP verb used to call this endpoint, and /timestamp is the URL itself. Now that we’ve gotten this bit out of the way, let’s create a module!

$ touch timestamp.py

Time to import the Falcon library:

import json

import falcon

import arrow

Note we’ve also import the json package and the arrow library. Now, let’s define a class for our resource:

class Timestamp(object):

	def on_get(self, req, resp):
		payload = {}
		payload['utc'] = arrow.utcnow().format('YYYY-MM-DD HH:mm:SS')
		payload['unix'] = arrow.utcnow().timestamp

		resp.body = json.dumps(payload)
		resp.status = falcon.HTTP_200

Let’s go through this snippet. We’ve defined a Timestamp class, and defined a class method called on_get - this function tells Falcon that when a GET request is issued to an endpoint for this resource, run the on_get function and provide the request and response objects as parameters.

After that, it’s smooth sailing - we create an empty dictionary, fill it up with the current UTC and UNIX timestamps, convert it to JSON and attach it to the response object.

Pretty simple, right? But sadly, that’s not all. We now need to create a Falcon server and hook up the resource class we’ve just defined to an actual endpoint.

$ touch app.py

Now, add the code below:

import falcon

from timestamp import Timestamp

api = application = falcon.API()

timestamp = Timestamp()

api.add_route('/timestamp', timestamp)

Here, we’ve defined a Falcon API, and initialized an instance of the resource class we created earlier. Then, we’ve hooked up the /timestamp endpoint with the class instance - and now we’re good to go! To test this API install gunicorn(pip install gunicorn), and run gunicorn app. Use Postman or simple cURL to test this:

$ curl http://localhost:8000/timestamp                                                    
{"utc": "2017-10-20 06:03:14", "unix": 1508479437}

And that does it!

Moving on

Once you’ve got the hang of Falcon, composing powerful RESTful APIs that interact with databases or messaging queues is very easy. Do check out the Falcon docs, as well as PyPI for interesting Falcon modules that keep popping up.