a brief introduction of the `REST without PUT` in ThoughtWorks Tech Radar

1. 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 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.

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 fit within the definition 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 'nounified'
request resources
• make our mutations be first class citizen nouns

13. Coarse grained resource API
- the pros
• fits perfectly with event sourcing
• CQRS api
• Reification of abstract concept

14. Coarse grained resource API
- the cons
• not enough variations to support all API
consumers
• the API may be difficult to maintain

15. 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.

16. 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