zxcv859500 / rest-api-example

Simple REST API example in Sinatra

REST API example application

This is a bare-bones example of a Sinatra application providing a REST API to a DataMapper-backed model.

The entire application is contained within the app.rb file.

config.ru is a minimal Rack configuration for unicorn.

run-tests.sh runs a simplistic test and generates the API documentation below.

It uses run-curl-tests.rb which runs each command defined in commands.yml.

Install

bundle install

Run the app

unicorn -p 7000

Run the tests

./run-tests.sh

REST API

The REST API to the example app is described below.

Get list of Things

Request

GET /thing/

curl -i -H 'Accept: application/json' http://localhost:7000/thing/

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:30 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 2

[]

Create a new Thing

Request

POST /thing/

curl -i -H 'Accept: application/json' -d 'name=Foo&status=new' http://localhost:7000/thing

Response

HTTP/1.1 201 Created
Date: Thu, 24 Feb 2011 12:36:30 GMT
Status: 201 Created
Connection: close
Content-Type: application/json
Location: /thing/1
Content-Length: 36

{"id":1,"name":"Foo","status":"new"}

Get a specific Thing

Request

GET /thing/id

curl -i -H 'Accept: application/json' http://localhost:7000/thing/1

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:30 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 36

{"id":1,"name":"Foo","status":"new"}

Get a non-existent Thing

Request

GET /thing/id

curl -i -H 'Accept: application/json' http://localhost:7000/thing/9999

Response

HTTP/1.1 404 Not Found
Date: Thu, 24 Feb 2011 12:36:30 GMT
Status: 404 Not Found
Connection: close
Content-Type: application/json
Content-Length: 35

{"status":404,"reason":"Not found"}

Create another new Thing

Request

POST /thing/

curl -i -H 'Accept: application/json' -d 'name=Bar&junk=rubbish' http://localhost:7000/thing

Response

HTTP/1.1 201 Created
Date: Thu, 24 Feb 2011 12:36:31 GMT
Status: 201 Created
Connection: close
Content-Type: application/json
Location: /thing/2
Content-Length: 35

{"id":2,"name":"Bar","status":null}

Get list of Things again

Request

GET /thing/

curl -i -H 'Accept: application/json' http://localhost:7000/thing/

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:31 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 74

[{"id":1,"name":"Foo","status":"new"},{"id":2,"name":"Bar","status":null}]

Change a Thing's state

Request

PUT /thing/:id/status/changed

curl -i -H 'Accept: application/json' -X PUT http://localhost:7000/thing/1/status/changed

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:31 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 40

{"id":1,"name":"Foo","status":"changed"}

Get changed Thing

Request

GET /thing/id

curl -i -H 'Accept: application/json' http://localhost:7000/thing/1

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:31 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 40

{"id":1,"name":"Foo","status":"changed"}

Change a Thing

Request

PUT /thing/:id

curl -i -H 'Accept: application/json' -X PUT -d 'name=Foo&status=changed2' http://localhost:7000/thing/1

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:31 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 41

{"id":1,"name":"Foo","status":"changed2"}

Attempt to change a Thing using partial params

Request

PUT /thing/:id

curl -i -H 'Accept: application/json' -X PUT -d 'status=changed3' http://localhost:7000/thing/1

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:32 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 41

{"id":1,"name":"Foo","status":"changed3"}

Attempt to change a Thing using invalid params

Request

PUT /thing/:id

curl -i -H 'Accept: application/json' -X PUT -d 'id=99&status=changed4' http://localhost:7000/thing/1

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:32 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 41

{"id":1,"name":"Foo","status":"changed4"}

Change a Thing using the _method hack

Request

POST /thing/:id?_method=POST

curl -i -H 'Accept: application/json' -X POST -d 'name=Baz&_method=PUT' http://localhost:7000/thing/1

Response

HTTP/1.1 200 OK
Date: Thu, 24 Feb 2011 12:36:32 GMT
Status: 200 OK
Connection: close
Content-Type: application/json
Content-Length: 41

{"id":1,"name":"Baz","status":"changed4"}

Change a Thing using the _method hack in the url

Request

POST /thing/:id?_method=POST

curl -i -H 'Accept: application/json' -X POST -d 'name=Qux' http://localhost:7000/thing/1?_method=PUT

Response

HTTP/1.1 404 Not Found
Date: Thu, 24 Feb 2011 12:36:32 GMT
Status: 404 Not Found
Connection: close
Content-Type: text/html;charset=utf-8
Content-Length: 35

{"status":404,"reason":"Not found"}

Delete a Thing

Request

DELETE /thing/id

curl -i -H 'Accept: application/json' -X DELETE http://localhost:7000/thing/1/

Response

HTTP/1.1 204 No Content
Date: Thu, 24 Feb 2011 12:36:32 GMT
Status: 204 No Content
Connection: close

Try to delete same Thing again

Request

DELETE /thing/id

curl -i -H 'Accept: application/json' -X DELETE http://localhost:7000/thing/1/

Response

HTTP/1.1 404 Not Found
Date: Thu, 24 Feb 2011 12:36:32 GMT
Status: 404 Not Found
Connection: close
Content-Type: application/json
Content-Length: 35

{"status":404,"reason":"Not found"}

Get deleted Thing

Request

GET /thing/1

curl -i -H 'Accept: application/json' http://localhost:7000/thing/1

Response

HTTP/1.1 404 Not Found
Date: Thu, 24 Feb 2011 12:36:33 GMT
Status: 404 Not Found
Connection: close
Content-Type: application/json
Content-Length: 35

{"status":404,"reason":"Not found"}

Delete a Thing using the _method hack

Request

DELETE /thing/id

curl -i -H 'Accept: application/json' -X POST -d'_method=DELETE' http://localhost:7000/thing/2/

Response

HTTP/1.1 204 No Content
Date: Thu, 24 Feb 2011 12:36:33 GMT
Status: 204 No Content
Connection: close