REST authentication for MagicStore
After cloning, create a virtual environment and install the requirements. For Linux and Mac users:
$ virtualenv venv
$ source venv/bin/activate
(venv) $ pip install -r requirements.txt
If you are on Windows, then use the following commands instead:
$ virtualenv venv
$ venv\Scripts\activate
(venv) $ pip install -r requirements.txt
To run the server use the following command:
(venv) $ python api.py
* Running on http://127.0.0.1:5000/
* Restarting with reloader
Then from a different terminal window you can send requests.
-
POST /api/users
Register a new user.
The body must contain a JSON object that definesusername
andpassword
fields.
On success a status code 201 is returned. The body of the response contains a JSON object with the newly added user. ALocation
header contains the URI of the new user.
On failure status code 400 (bad request) is returned.
Notes:- The password is hashed before it is stored in the database. Once hashed, the original password is discarded.
- In a production deployment secure HTTP must be used to protect the password in transit.
-
GET /api/users/<int:id>
Return a user.
On success a status code 200 is returned. The body of the response contains a JSON object with the requested user.
On failure status code 400 (bad request) is returned. -
GET /api/token
Return an authentication token.
This request must be authenticated using a HTTP Basic Authentication header.
On success a JSON object is returned with a fieldtoken
set to the authentication token for the user and a fieldduration
set to the (approximate) number of seconds the token is valid.
On failure status code 401 (unauthorized) is returned. -
GET /api/resource
Return a protected resource.
This request must be authenticated using a HTTP Basic Authentication header. Instead of username and password, the client can provide a valid authentication token in the username field. If using an authentication token the password field is not used and can be set to any value.
On success a JSON object with data for the authenticated user is returned.
On failure status code 401 (unauthorized) is returned.
The following curl
command registers a new user with username test_user
and password pwd
:
$ curl -i -X POST -H "Content-Type: application/json" -d '{"username":"test_user","password":"pwd"}' http://127.0.0.1:5000/api/users
HTTP/1.0 201 CREATED
Content-Type: application/json
Content-Length: 27
Location: http://127.0.0.1:5000/api/users/1
Server: Werkzeug/0.9.4 Python/2.7.3
Date: Thu, 28 Nov 2013 19:56:39 GMT
{
"username": "test_user"
}
Request an authentication token using user credentials:
$ curl -u test_user:pwd -i -X GET http://127.0.0.1:5000/api/token
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 139
Server: Werkzeug/0.9.4 Python/2.7.3
Date: Thu, 28 Nov 2013 20:04:15 GMT
{
"duration": 600,
"token": "eyJhbGciOiJIUzI1NiIsImV4cCI6MTM4NTY2OTY1NSwiaWF0IjoxMzg1NjY5MDU1fQ.eyJpZCI6MX0.XbOEFJkhjHJ5uRINh2JA1BPzXjSohKYDRT472wGOvjc"
}
Save token (replace token parameter with token) to file: $ echo 'Authorization:Token ' > token.txt
These credentials can now be used to access protected resources:
$ curl -i -H "$(< token.txt)" -XGET http://127.0.0.1:5000/api/resource
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 30
Server: Werkzeug/0.9.4 Python/2.7.3
Date: Thu, 28 Nov 2013 20:02:25 GMT
{
"data": "Hello, test_user!"
}
To upload file: curl -i -H "$(< token.txt)" -XPOST -F file=@ http://127.0.0.1:5000/
To download file: $ curl -i -H "$(< token.txt)" -GET http://127.0.0.1:5000/uploads/ HTTP/1.0 200 OK Content-Type: application/json Content-Length: 30 Server: Werkzeug/0.9.4 Python/2.7.3 Date: Thu, 28 Nov 2013 20:05:08 GMT
{
"data": "Hello, test_user!"
}
Once the token expires it cannot be used anymore and the client needs to request a new one. Each file uploaded is also associated with the uploading user and cannot be accessed by any other.