This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!
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.

Release History

Release History


This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
rest-api-blueprint-0.1.tar.gz (83.9 kB) Copy SHA256 Checksum SHA256 Source Nov 6, 2012

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting