rest-api-blueprint

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.

Status

Reasonably complete now. See open issues.

Quick tour

Start the example app server:

-/code/rest-api-blueprint$ python server.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$ 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

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

0.1

Nov 6, 2012

Download files

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

Source Distribution

rest-api-blueprint-0.1.tar.gz (83.9 kB view details)

Uploaded Nov 6, 2012 Source

File details

Details for the file rest-api-blueprint-0.1.tar.gz.

File metadata

Download URL: rest-api-blueprint-0.1.tar.gz
Upload date: Nov 6, 2012
Size: 83.9 kB
Tags: Source
Uploaded using Trusted Publishing? No

File hashes

Hashes for rest-api-blueprint-0.1.tar.gz
Algorithm	Hash digest
SHA256	`d67677cbbb0e183a5cda4cff208d349dd4b721f82d2df7dddc5470f7f9f6642d`
MD5	`243888ad62ac888d194881deb55fb892`
BLAKE2b-256	`3dc1520fc4dbe9146eb1f859073ef06d76485a9eb78f2f008ea7a42591005f12`