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

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.