wheezy web: RESTful API Design

In this article we are going to explore a simple RESTful API created with wheezy.web framework. The demo implements a CRUD for tasks. Includes entity validation, content caching with dependencies and functional test cases. The source code is structured with well defined actors (you can read more about it here).

Design

The following convention is used with respect to operation, HTTP method (verb) and URL:

List:   GET    /api/v1/tasks
Add:    POST   /api/v1/tasks
Get:    GET    /api/v1/task/{task_id}
Update: PUT    /api/v1/task/{task_id}
Remove: DELETE /api/v1/task/{task_id}

The task entity consists of the following attributes: task_id, title and status. The source code is available here. Please download before proceeding any further.

Setup

Create a virtual environment and run application:

virtualenv env
env/bin/pip install wheezy.web
env/bin/python app.py

List Tasks

curl -i http://localhost:8080/api/v1/tasks

HTTP/1.1 200 OK
Date: Wed, 29 Oct 2014 14:14:43 GMT
Server: WSGIServer/0.1 Python/2.7.6
Content-Type: application/json; charset=UTF-8
Cache-Control: private, max-age=0
Expires: Wed, 29 Oct 2014 14:14:43 GMT
Last-Modified: Wed, 29 Oct 2014 14:14:43 GMT
ETag: "d0d2d53e"
Content-Length: 146

{"tasks":[{"status":1,"task_id":"1","title":"Task #1"},
{"status":2,"task_id":"2","title":"Task #2"},
{"status":1,"task_id":"3","title":"Task #3"}]}

Get Task

curl -i http://localhost:8080/api/v1/task/1

HTTP/1.1 200 OK
Date: Wed, 29 Oct 2014 14:17:34 GMT
Server: WSGIServer/0.1 Python/2.7.6
Content-Type: application/json; charset=UTF-8
Cache-Control: private, max-age=0
Expires: Wed, 29 Oct 2014 14:17:34 GMT
Last-Modified: Wed, 29 Oct 2014 14:17:34 GMT
ETag: "a552062f"
Content-Length: 53

{"task":{"status":1,"task_id":"1","title":"Task #1"}}

Add Task

curl -i -H "Content-Type: application/json" -X POST \
  -d '{"title": "Test"}' http://localhost:8080/api/v1/tasks

HTTP/1.1 201 Created
Date: Wed, 29 Oct 2014 14:15:13 GMT
Server: WSGIServer/0.1 Python/2.7.6
Content-Type: application/json; charset=UTF-8
Cache-Control: private
Content-Length: 24

{"task":{"task_id":"4"}}

Update Task

curl -i -H "Content-Type: application/json" -X PUT \
  -d '{"status": 1}' http://localhost:8080/api/v1/task/1

HTTP/1.1 200 OK
Date: Wed, 29 Oct 2014 14:18:46 GMT
Server: WSGIServer/0.1 Python/2.7.6
Content-Type: application/json; charset=UTF-8
Cache-Control: private
Content-Length: 15

{"status":"OK"}

Delete Task

curl -i -X DELETE http://localhost:8080/api/v1/task/4

The output is similar to update task.

Validation Errors

curl -i -H "Content-Type: application/json" -X POST \
  -d '{}' http://localhost:8080/api/v1/tasks

HTTP/1.1 200 OK
Date: Wed, 29 Oct 2014 14:29:50 GMT
Server: WSGIServer/0.1 Python/2.7.6
Content-Type: application/json; charset=UTF-8
Cache-Control: private
Content-Length: 61

{"errors":{"title":["Required field cannot be left blank."]}}

Task Not Found

curl -i http://localhost:8080/api/v1/task/0

HTTP/1.1 404 Not Found
Date: Wed, 29 Oct 2014 14:32:14 GMT
Server: WSGIServer/0.1 Python/2.7.6
Content-Type: text/html; charset=UTF-8
Cache-Control: private, max-age=0
Expires: Wed, 29 Oct 2014 14:32:14 GMT
Last-Modified: Wed, 29 Oct 2014 14:32:14 GMT
ETag: "43be58cc"
Content-Length: 0

HTTP Caching

Ensure a value for If-None-Match corresponds to one returned by list tasks command header ETag.

curl -i -H 'If-None-Match: "d0d2d53e"' \
  http://localhost:8080/api/v1/tasks

HTTP/1.1 304 Not Modified
Date: Wed, 29 Oct 2014 15:13:13 GMT
Server: WSGIServer/0.1 Python/2.7.6
Content-Type: application/json; charset=UTF-8
Cache-Control: private, max-age=0
Expires: Wed, 29 Oct 2014 15:12:39 GMT
Last-Modified: Wed, 29 Oct 2014 15:12:39 GMT
ETag: "d0d2d53e"
Content-Length: 0

Functional Test Cases

The functional test cases can be downloaded from here.

env/bin/pip install pytest
env/bin/py.test test_app.py