Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!

Close

REST API Blueprint

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.

Installation

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. It is available on pypi/rest-api-blueprint and can be installed with:

pip install rest-api-blueprint

Status

Reasonably complete now. See open issues.

Quick tour

Start the example app server:

~/code/rest-api-blueprint$ python runserver.py
 * Running on http://127.0.0.1:5000/
 * 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/restapiblueprint$ 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/all.py:14
    And I have an empty database                                     # features/steps/all.py:19
    And I am a valid API user                                        # features/steps/all.py:27
    And I use an Accept header of "application/json"                 # features/steps/all.py:32
    When I send a DELETE request to "people/fred"                    # features/steps/all.py:101
    Then the response status should be "404"                         # features/steps/all.py:109
    And the JSON at path "status" should be "error"                  # features/steps/all.py:119
    And the JSON at path "message" should be "Person does not exist" # features/steps/all.py:119

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

Make the API docs (Doc details):

~/code/rest-api-blueprint$ ./make_apidocs.sh
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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<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"})
True

>>>api.people.tim.get()
{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 setup.py nosetests

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

python setup.py 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 setup.py develop

or

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.

Recent activity

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.