Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

Pedagogical blueprint of a REST API in Flask.

Project description

This is an exploration into how best to create a REST API using Python (version 2.7) and the excellent micro-web framework Flask. It aims to be a pedagogical blueprint rather than a library or utility. A more prosaic and honest statement of the goal is to provide a clean exposition with code of my current (but evolving) tastes in the design and structure of a REST API built with Python and Flask.

The scope includes automatic testing, documentation, authentication, capability switching, data formats, mime types, and unicode. As the focus is on REST API structure and expression, the scope does not include things like ORM’s and templating engines.

See the Wiki for discussion and explanation. Otherwise the repository code is authoritative.

Note that this is not a library so much as an approach to be read and copied. However there are clearly parts which are usefully referenced (e.g. the BDD steps or the lib). This is possible by installing as a package and importing.


Reasonably complete now. See open issues.

Quick tour

Start the example app server:

-/code/rest-api-blueprint$ python
 * Running on
 * Restarting with reloader

Add person details with the example app:

~/code/rest-api-blueprint$ curl -X PUT localhost:5000/v1/people/fred -H 'Content-Type: application/json' -d '{"email": "a@b.c"}'
  "status": "ok"

Retrieve person details with the example app:

~/code/rest-api-blueprint$ curl -X GET localhost:5000/v1/people/fred -H 'Accept: application/json'
  "status": "ok",
  "result": {
    "comment": null,
    "name": "fred",
    "email": "a@b.c"

Run the BDD tests (BDD details):

~/code/rest-api-blueprint$ behave
Feature: Delete a person # features/delete_person.feature:1
  As an API client
  I want to be able to remove a person

  Background: Reset and have a valid user  # features/delete_person.feature:5

  Scenario: Cannot delete a person before they exist                 # features/delete_person.feature:11
    Given I am using version "v1"                                    # features/steps/
    And I have an empty database                                     # features/steps/
    And I am a valid API user                                        # features/steps/
    And I use an Accept header of "application/json"                 # features/steps/
    When I send a DELETE request to "people/fred"                    # features/steps/
    Then the response status should be "404"                         # features/steps/
    And the JSON at path "status" should be "error"                  # features/steps/
    And the JSON at path "message" should be "Person does not exist" # features/steps/

  Scenario: Delete a person                                          # features/delete_person.feature:17
    Given I am using version "v1"                                    # features/steps/

Make the API docs (Doc details):

~/code/rest-api-blueprint$ ./
Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [100%] people
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] people
writing additional files... search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.
Copying ansi stylesheet... done

Be redirected to the on-line docs:

~/code/rest-api-blueprint$ curl -X GET localhost:5000/v1/people/fred
<p>You should be redirected automatically to target URL: <a href="static/apidocs/people.html">static/apidocs/people.html</a>.  If not click the link.

Interacting using Slumber:

>>>import slumber
>>>api=slumber.API('http://localhost:5000/v1/', append_slash=False)
>>>api.people.tim.put({"email": "a@b.c"})

{u'result': {u'comment': None, u'email': u'a@b.c', u'name': u'tim'}, u'status': u'ok'}

To provide a template packaged structure, everything is packaged using distribute.

To run the tests:

python nosetests

To build a package for distribution and installation with pip etc:

python sdist

The package is in the dist/ directory, and can be installed with

pip install rest-api-blueprint-0.1.tar.gz

To install during development:

python develop


pip install -e .

(which will also install any dependent packages.)

What’s next?

Intrigued? Read the Wiki and check out the code.

Please send me feedback, raise bugs or requests using the bitbucket Issue Tracker, or clone and improve (ideally with create pull requests) as per the permissive BSD 2-Clause license.

Project details

Release history Release notifications | RSS feed

This version


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for rest-api-blueprint, version 0.1
Filename, size File type Python version Upload date Hashes
Filename, size rest-api-blueprint-0.1.tar.gz (83.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page