際際滷

際際滷Share a Scribd company logo

rest without put

Xiaojun REN
Xiaojun REN

This document discusses REST (Representational State Transfer) and resource-oriented APIs. It notes that REST relies on a stateless and cacheable protocol. Resources can represent any concept that can be referenced, like documents, services, objects, or collections. Typical CRUD APIs use GET, POST, PUT, and DELETE on resources, but PUT can cause problems for complex state changes. Instead of PUT, it's better to POST new "event resources" that represent actions. This allows mutations to be first-class resources and avoids losing context of the original update trigger. Coarse-grained, resource-oriented APIs fit with approaches like event sourcing and CQRS. The granularity of resources is important to consider.

1 of 16
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 鍖t within the de鍖nition 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 Fieldings dissertation.
Resource Examples: in a blog domain post, comment, image, tag in a bank domain customer, account
REST Api A typical CRUD based Api: GET /posts GET /posts/:id POST /posts { title: a simple post, content: } PUT /posts {content: new content}
REST Api A 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 Api Transfer 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 鍖t within the de鍖nition of a resource
Event Resource POST /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 'nouni鍖ed' request resources make our mutations be 鍖rst class citizen nouns
Coarse grained resource API - the pros 鍖ts perfectly with event sourcing CQRS api Rei鍖cation of abstract concept
Coarse grained resource API - the cons not enough variations to support all API consumers the API may be dif鍖cult to maintain
key tips Granularity of resource Theres 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

More Related Content

rest without put

  • 2. REST REST stands for Representational State Transfer. (It is sometimes spelled "ReST".) It relies on a stateless, client-server, cacheable communications protocol
  • 3. 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 鍖t within the de鍖nition 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 Fieldings dissertation.
  • 4. Resource Examples: in a blog domain post, comment, image, tag in a bank domain customer, account
  • 5. REST Api A typical CRUD based Api: GET /posts GET /posts/:id POST /posts { title: a simple post, content: } PUT /posts {content: new content}
  • 6. REST Api A 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}
  • 7. REST Api Transfer 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}
  • 8. CRUD REST API - the cons Too much conversations between providers and consumers Too much internal domain knowledge into client
  • 9. 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
  • 10. Resource(revisit) any concept that might be the target of an author's hypertext reference must 鍖t within the de鍖nition of a resource
  • 11. Event Resource POST /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}
  • 12. REST without PUT consumers are forced to post new 'nouni鍖ed' request resources make our mutations be 鍖rst class citizen nouns
  • 13. Coarse grained resource API - the pros 鍖ts perfectly with event sourcing CQRS api Rei鍖cation of abstract concept
  • 14. Coarse grained resource API - the cons not enough variations to support all API consumers the API may be dif鍖cult to maintain
  • 15. key tips Granularity of resource Theres 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.