SparREST

A REST sparring to learn and test front-end technologies by making HTTP requests.

SparREST works as a SimpleHTTPServer serving your static files in the working directory, and it also works as an API Rest that stores any data you send to it just by using /api/<resource> at the begining of your URL.

Tutorial

Let's create a fighters database.

Running the server

mkdir FigthersDB
cd FigthersDB
python server.py

And here we go!

Starting a server on port 8000. Use CNTRL+C to stop the server.

You can run the server in a different IP address and port by using:

python server.py <IP> <PORT>

For example:

python server.py 0.0.0.0 # runs the server in 0.0.0.0:8000
python server.py 0.0.0.0 1234 # runs the server in 0.0.0.0:1234

Creating a welcome page

echo "<h1>Hello World</h1>" > index.html

And to recover the welcome page (that is a static file):

curl http://localhost:8000/

And we have what we want:

<h1>Hello World</h1>

Creating our first fighter

Making a POST to the resource that we want (fighters in this case) with the "Content-Type: application/json" header and the body in JSON format:

curl -H "Content-Type: application/json" -X POST -d '{"name": "Chuck Norris", "style": "Karate"}' http://localhost:8000/api/fighters

And it returns a JSON object with an ID autogenerated:

{  
   "style":"Karate",
   "name":"Chuck Norris",
   "id":1
}

This will create a db folder in your working directory and a fighters directory inside with a file called 1.

We can also bulk insert a bunch of fighters by using a JSON array:

curl -H "Content-Type: application/json" -X POST -d '[{"name": "Bruce Lee", "style": "Kung Fu"}, {"name": "Rocky Balboa", "style": "Boxing"}]' http://localhost:8000/api/fighters

This will two files inside our db/fighters folder called 2 and 3. You got it?

[  
   {  
      "style":"Kung Fu",
      "name":"Bruce Lee",
      "id":2
   },
   {  
      "style":"Boxing",
      "name":"Rocky Balboa",
      "id":3
   }
]

Retrieving all fighters

Just make a GET request to http://localhost:8000/api/fighters:

curl http://localhost:8000/api/fighters

It returns a JSON list with all the fighters that we have inserted:

[  
   {  
      "style":"Karate",
      "name":"Chuck Norris",
      "id":1
   },
   {  
      "style":"Kung Fu",
      "name":"Bruce Lee",
      "id":2
   },
   {  
      "style":"Boxing",
      "name":"Rocky Balboa",
      "id":3
   }
]

Retrieving just one fighter

To recover a single fighter, we have to call the URL using the fighter ID http://localhost:8000/api/fighters/<resource_id> with the HTTP PUT method.

We're gonna take some risks, and retrieve Chuck Norris:

curl http://localhost:8000/api/fighters/1

It returns a JSON list with all the fighters that we have inserted:

{  
   "style":"Karate",
   "name":"Chuck Norris",
   "id":1
}

Updating a fighter

To update a fighter, we have to make a PUT request to the fighter URL.

To update Rocky:

curl -H "Content-Type: application/json" -X PUT -d '{"name": "Robert Rocky Balboa", "style": "Boxing"}' http://localhost:8000/api/fighters/3

And it returns the fighter updated:

{  
   "style":"Boxing",
   "name":"Robert Rocky Balboa",
   "id":"3"
}

Deleting a fighter

To recover a fighter, we have to call the URL using the fighter ID http://localhost:8000/api/fighters/<resource_id> with the HTTP DELETE method:

If we delete Rocky:

curl -H "Content-Type: application/json" -X DELETE http://localhost:8000/api/fighters/3

It returns just a 204 No Content HTTP response and if we try to recover the deleted fighter:

curl http://localhost:8000/api/fighters/3

We have a 404 Not found HTTP response with the content:

{  
   "404":"Resource fighters/3 not found"
}

Ordering

You can specify what field or fields you want to retrieve a resource ordered by using the _order query parameter. For example:

# Return fighters ordered by name field ascending.
curl http://localhost:8000/api/fighters/?_order=name 

# Return fighters ordered by name field descending.
curl http://localhost:8000/api/fighters/?_order=-name 

# Return fighters ordered by name ascending and then by style descending.
curl http://localhost:8000/api/fighters/?_order=name,-style

Selecting fields to retrieve

You can specify what field or fields you want to retrieve from a resource in a GET request by using the _fields query parameter. For example:

# Returns only the fighters id and name
curl http://localhost:8000/api/fighters/?_fields=id,name 

# Returns only the fighter name and style
curl http://localhost:8000/api/fighters/1?_fields=name,style 

Available API endpoints

GET /api/<resource_name>

It looks for files in db/<resource_name> folder and returns the content in JSON.

If the folder does not exist, a 404 HTTP error is returned.

POST /api/<resource_name>

It creates a new item in the db/<resource_name> (creating the db/<resource_name> folder if it doesn't exist).

Is mandatory to send the a valid Content-Type header to the request and the body must have a valid format.

It can receive a JSON object or a JSON array of JSON objects.

If the folder does not exist, a 404 HTTP error is returned.

If the Content-Type or the request body is not valid header is not set, a 400 HTTP error is returned.

GET /api/<resource_name>/<resource_id>

Retrieves an object stored in the file db/<resource_name>/<resource_id>.

If the file does not exist, a 404 HTTP error is returned.

PUT /api/<resource_name>/<resource_id>

Replaces the content stored in the file db/<resource_name>/<resource_id>) by the body of the request.

If the file does not exist, a 404 HTTP error is returned.

If the Content-Type or the request body is not valid header is not set, a 400 HTTP error is returned.

PATCH /api/<resource_name>/<resource_id>

Update only the keys sent for the content stored in the file db/<resource_name>/<resource_id>) by the value sent.

If the file does not exist, a 404 HTTP error is returned. If the Content-Type or the request body is not valid header is not set, a 400 HTTP error is returned.

DELETE /api/<resource_name>/<resource_id>

Deletes the file db/<resource_name>/<resource_id>).

If the file does not exist, a 404 HTTP error is returned.

Supported Content-Types

• application/json
• application/x-www-form-urlencoded
• multipart/form-data

NOTE: SparREST will always respond in JSON. SparREST loves JSON.

Uploading files

Just send a POST to any resource with multipart/form-data Content-type (and format) and SparREST will manage the file upload by uploading the file to the uploads folder (automatically created) and returning the uploaded file URL as value of the JSON field response. Example:

{
  "id": 31,
  "style": "Free Style",
  "name": "Bud Spencer",
  "photo": "/uploads/f0ec12a8-445e-11e6-88f7-a45e60dc3607.png"
}

Changelog

0.3 - Drago

CHANGES

• Select the IP address to run the server (special thanks to @dfreniche for his contribution)
• PATCH method supported
• Added support for application/x-www-form-urlencoded and multipart/form-data content types
• Ordering feature
• Fields selection feature
• File uploads
• Documentation improvements
• Minor bugfixes

0.2 - Creed

BUGFIXES

• Now it runs on Windows too
• Content-Type header validation changed to play with AngularJS

CHANGES

• When you POST a single JSON object, the response is a single JSON object instead of a JSON list/array with the object.

0.1 - Balboa

• First version, started in the train from Madrid to Valencia for the PyConES 2015.
• It supports Python 2 and 3
• I hope you enjoy it!

More

• Based on the Gist of Ville Svärd (@codification): https://gist.github.com/codification/1393204
• Excuse me the typos.