REST VERBS - jordy33/turbogears_tutorial GitHub Wiki
Rest Verbs
HTTP GET
Use GET requests to retrieve resource representation/information only โ and not to modify it in any way. As GET requests do not change the state of the resource, these are said to be safe methods. Additionally, GET APIs should be idempotent, which means that making multiple identical requests must produce the same result every time until another API (POST or PUT) has changed the state of the resource on the server.
If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process.
For any given HTTP GET API, if the resource is found on the server then it must return HTTP response code 200 (OK) โ along with response body which is usually either XML or JSON content (due to their platform independent nature).
In case resource is NOT found on server then it must return HTTP response code 404 (NOT FOUND). Similarly, if it is determined that GET request itself is not correctly formed then server will return HTTP response code 400 (BAD REQUEST).
Example request URIs
HTTP GET http://www.appdomain.com/users
HTTP GET http://www.appdomain.com/users?size=20&page=5
HTTP GET http://www.appdomain.com/users/123
HTTP GET http://www.appdomain.com/users/123/address .
HTTP POST
Use POST APIs to create new subordinate resources, e.g. a file is subordinate to a directory containing it or a row is subordinate to a database table. Talking strictly in terms of REST, POST methods are used to create a new resource into the collection of resources.
Ideally, if a resource has been created on the origin server, the response SHOULD be HTTP response code 201 (Created) and contain an entity which describes the status of the request and refers to the new resource, and a Location header.
Many times, the action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either HTTP response code 200 (OK) or 204 (No Content) is the appropriate response status.
Responses to this method are not cacheable, unless the response includes appropriate Cache-Control or Expires header fields.
Please note that POST is neither safe nor idempotent and invoking two identical POST requests will result in two different resources containing the same information (except resource ids).
Example request URIs
HTTP POST http://www.appdomain.com/users
HTTP POST http://www.appdomain.com/users/123/accounts
HTTP PUT
Use PUT APIs primarily to update existing resource (if the resource does not exist then API may decide to create a new resource or not). If a new resource has been created by the PUT API, the origin server MUST inform the user agent via the HTTP response code 201 (Created) response and if an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.
The difference between the POST and PUT APIs can be observed in request URIs. POST requests are made on resource collections whereas PUT requests are made on an individual resource.
Example request URIs
HTTP PUT http://www.appdomain.com/users/123
HTTP PUT http://www.appdomain.com/users/123/accounts/456
HTTP DELETE
As the name applies, DELETE APIs are used to delete resources (identified by the Request-URI).
A successful response of DELETE requests SHOULD be HTTP response code 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has been queued, or 204 (No Content) if the action has been performed but the response does not include an entity.
DELETE operations are idempotent. If you DELETE a resource, itโs removed from the collection of resource. Repeatedly calling DELETE API on that resource will not change the outcome โ however calling DELETE on a resource a second time will return a 404 (NOT FOUND) since it was already removed. Some may argue that it makes DELETE method non-idempotent. Itโs a matter of discussion and personal opinion.
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries SHOULD be treated as stale. Responses to this method are not cacheable.
Example request URIs
HTTP DELETE http://www.appdomain.com/users/123
HTTP DELETE http://www.appdomain.com/users/123/accounts/456 .
Download SOAP UI from here and install It will be used for testing the verbs PUT,POST,DELETE
In Controllers folder add pets.py then add the following:
# -*- coding: utf-8 -*-
"""The base Controller API."""
from tg import RestController
from tg import expose
__all__ = ['PetsController']
class PetsController(RestController):
@expose('json')
def get_all(self):
return dict(name='Boony',breed='Dog')
@expose('json')
def post(self, name,breed):
print("POST Name: {} Breed: {}".format(name,breed))
return dict(name=name,breed=breed)
@expose('json')
def put(self, name,breed):
print("PUT Name: {} Breed: {}".format(name,breed))
return dict(name=name,breed=breed)
@expose('json')
def post_delete(self, name,breed):
print("DELETE Name: {} Breed: {}".format(name,breed))
return dict(name=name,breed=breed)
At top of root.py add the following:
from myprojectname.controllers.pets import PetsController
In the Root Controller class add:
pets = PetsController()
Test the code:
http://localhost:8080/pets
Will Reply
{"breed": "Dog", "name": "Boony"}
For the other verbs use soap UI
Create new project:
Do a Post:
Check output:
| Method | Description | Example Method(s) / URL(s) |
+=================+==============================================================+============================================+
| get_one | Display one record. | GET /movies/1 |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| get_all | Display all records in a resource. | GET /movies/ |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| get | A combo of get_one and get_all. | GET /movies/ |
| | +--------------------------------------------+
| | | GET /movies/1 |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| new | Display a page to prompt the User for resource creation. | GET /movies/new |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| edit | Display a page to prompt the User for resource modification. | GET /movies/1/edit |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| post | Create a new record. | POST /movies/ |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| put | Update an existing record. | POST /movies/1?_method=PUT |
| | +--------------------------------------------+
| | | PUT /movies/1 |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| post_delete | Delete an existing record. | POST /movies/1?_method=DELETE |
| | +--------------------------------------------+
| | | DELETE /movies/1 |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| get_delete | Display a delete Confirmation page. | GET /movies/1/delete |
+-----------------+--------------------------------------------------------------+--------------------------------------------+
| delete | A combination of post_delete and get_delete. | GET /movies/delete |
| | +--------------------------------------------+
| | | DELETE /movies/1 |
| | +--------------------------------------------+
| | | DELETE /movies/ |
| | +--------------------------------------------+
| | | POST /movies/1/delete |
| | +--------------------------------------------+
| | | POST /movies/delete |
+-----------------+--------------------------------------------------------------+--------------------------------------------+