REST without PUT

REST

REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications protocol

Resource“The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.”

- Roy Fielding’s dissertation.

Resource

• Examples:

• in a blog domain

• post, comment, image, tag

• in a bank domain

• customer, account

REST ApiA typical CRUD based Api:

• GET  /posts  

• GET  /posts/:id  

• POST  /posts    

       {  “title”:  “a  simple  post”,  “content”:  “…”}  

• PUT  /posts  

       {“content”:  “new  content”}

REST ApiA typical CRUD based Api:

• GET  /customer/:id/accounts  

• GET  /customer/:id/accounts/:id  

• POST  /customer/:id/accounts  

         {  “balance”:  x}  

• PUT  /customer/:id/accounts  

       {  “balance”:  y}

REST ApiTransfer 30$ from account 1 to account 2

initial  state:  

account  11  balance  50$  

account  21  balance  10$  

PUT  /customer/1/accounts/11  

       {  “balance”:  20}  

PUT  /customer/2/accounts/21  

       {  “balance”:  40}

CRUD REST API - the cons

• Too much conversations between providers and consumers

• Too much internal domain knowledge into client

problem of PUT

• complex state transitions can lead to synchronous cruddy CRUD

• usually throws away a lot of information that was available at the time the update was triggered

Resource(revisit)

any concept that might be the target of an author's hypertext reference must fit within the definition of a resource

Event ResourcePOST  /transactions  

{  from:  “1”,  to:  “2”,  amount:  “20”  }  

POST  /customer_enrolment  

{customer_id:  1,  balance:  10}  

POST  /change_of_addresses  

{customer_id:  1,  address:  “Church  St  511  Richmond  VIC  3000”}

REST without PUT

• consumers are forced to post new 'nounified' request resources

• make our mutations be first class citizen nouns

Coarse grained resource API - the pros

• fits perfectly with event sourcing

• CQRS api

• Reification of abstract concept

Coarse grained resource API - the cons

• not enough variations to support all API consumers

• the API may be difficult to maintain

key tips• Granularity of resource

• There’s no hard dependency between Resource and Domain model

• Domain driven design applies to the implementation side of things (including API implementation)

• Resources in REST API drive the API design and contract.

References• http://www.thoughtworks.com/insights/blog/rest-

api-design-resource-modeling

• http://engineering.linkedin.com/distributed-systems/log-what-every-software-engineer-should-know-about-real-time-datas-unifying

• http://martinfowler.com/eaaDev/EventSourcing.html

• http://martinfowler.com/bliki/CQRS.html