rest beyond crud

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