rest beyond crud
DESCRIPTION
Sample REST API for operations that go beyond the create, read, update, deleteTRANSCRIPT
REST beyond CRUD
Paulo Sousa
@pagsousa
Sample REST API for “more than CRUD”
Examples Shopping Cart Book printing
Shopping cart
Create a new cart Obtain its contents Add an item Remove an item Empty the cart Calculate full charges Proceed to checkout
Base URI
Cart as top level resource http://example.org/carts/
Or
Cart as sub resource of user http://example.org/users/{id}/cart
Creating a cart
Cart as top level resourcePOST example.org/carts/
Would return a new cart resource URI201 Created
Location: http://example.org/carts/123
Cart as sub resource of user Not necessary, cart is already available http://example.org/users/{id}/cart
Obtain the content of the cart Issue a GET to the resource
GET /carts/{id}orGET /users/{id}/cart
On begining, would return a representation of the empty cart200 Ok{itens: []}
Otherwise would return the current content of the cart200 Ok{itens: [{id:..., qty:...}, ...]}
Add an item
PUT an updated representation of the entire cartPUT /carts/{id}{itens: [{id: ..., qty: ...},{id: ..., qty: ...}]}
Or
Treat the cart as a collection and POST a new itemPOST /carts/{id}/itens{id: ..., qty: ...}
Would return the URI of the newly added item201 CreatedLocation: http://example.org/carts/123/itens/456
Remove an item
PUT an updated representation of the entire cartPUT /carts/{id}
{itens: [{id: ..., qty: ...}]}
Or
Treat the cart as a collection and DELETE an itemDELETE /carts/{id}/itens/{itemid}
Empty the cart
PUT an updated representation of the empty cartPUT /carts/{id}
{itens: []}
Or
Treat the cart as a collection and DELETE the itensDELETE /carts/{id}/itens
Calculate full charges
If the calculation is transitory, just GET the result of the calculationGET /carts/{id}/fullchargesorGET /users/{id}/cart/fullcharges
Would return{itens: 100, taxes: 23, shipping: 12, total: 140, currency:
EUR}
Or an updated shopping cart representation with charges element{itens: [...], charges: {...}}
This element should be considered transient and not part of the resource Former approach is “better” as it is a separate resource
Calculate full charges (2)
If charges are to be considered a persistent part part of the resource By doing the calculation you are in fact changing the resource i.e., Have side effect, so GET is to be avoided
POST the request for the calculation, e.g.
POST /carts/{cid}{fullcharges: yes}
Would return updated shopping cart{itens: [...], charges: {...}}
Procceed to checkout
POST an order with the content of the shopping cart?GET /carts/{id}/as-orderPOST /orders
Or
POST to a check-out controller?POST /carts/{id}/checkout
or
POST /checkout?cart={id}or
POST /salesprocess/checkout
Book printing example
Get a pdf of a book Print a book
Book printing example
Download a pdf representation of a book for printing at the clientGET /books/{id}?template={tmpl}
Accept: application/pdf
Book printing example
Print a book (at the server)POST /books/{id}/print?printer=hp01
In fact what we want is to order a printing service...POST /printorders/
{what: “/books/{id}”, quality: ..., ... }
202 Accepted
Location: /printorders/3Af42X
Not very beatiful
Book printing example
Query the status GET /printorders/{id}
200 Ok
{status = “pending”, ...}
Book printing example
Cancel the printing orderDELETE /printorders/{id}
200 Ok
If the order could not be deleted anymore (e.g., already printing), the service would return a 405 Method Not Allowed