resource oriented design
TRANSCRIPT
RESOURCE ORIENTED DESIGN
Gabriele Lana
WHAT IS REST?
WHAT IS… NOTa Protocol an Architecture a Software a Standard another name for Web Services a Buzzword
REST IS…A Software Architectural Style, a set of Constraints on Component Interaction that, when obeyed, cause the resulting Architecture to have certain properties
REST WHY?“... the motivation for developing REST was to create an architectural model for how the Web should work, such that it could serve as the guiding framework for the Web protocol standards”
Leonard Richardson & Sam Ruby “RESTful Web Services”
O’Reilly 2007
Step by St
ep
DESIGN RESTFUL WEB SERVICES
1. EVERY RESOURCEMUST BEIDENTIFIED
2. DESIGN THE URLS
2. DESIGN THE URLS
BAD
URL GRAMMARcollections, filters and selectors
/users/544a65c3da90ea5bed437cce
/conversion-rate/20141024..20141027
/conversion-rate/20141024
/conversion-rate/20141024,20141027
`/users` is the collection, ID is the filter
/users/registered
`/registered` it’s a property that works as a filter
Filters could be nicely combined
URL GRAMMARaliases are good
> GET /users/544a65c3da90ea5bed437cce < 301 Moved Permanently < Link: </users/544a65c3da90ea5bed437cce>; rel="canonical"
Permanent alias
> GET /users/me < 302 Found < Location: /users/544a65c3da90ea5bed437cce
Depends on context
> GET /maps/here < 200 Ok < Link: </maps/lat/45.4557648/lon/9.0995368>; rel="canonical"
Depends on context
URL GRAMMARaliases are good
> GET /conversion-rate/yesterday < 302 Found < Location: /conversion-rate/20141027
Depends on time
> GET /users/underage < 302 Found < Location: /users?age=(less-than-or-equal,18)
Could hide complex but common queries
URL GRAMMARstandard actions
> POST /users < 201 Created < Location: /users/544a65c3da90ea5bed437cce
Creates a new resource in the collection
> GET /users/544a65c3da90ea5bed437cce < 200 OK
Show the resource
> DELETE /users/544a65c3da90ea5bed437cce < 204 No Content
Remove the resource from the collection What really means depends on the collection/resource
URL GRAMMARstandard actions
> DELETE /login < 301 Moved Permanently < Set-Cookie: token=deleted; path=/; expires=… < Location: /
Delete the login could mean to logout
> PUT /users/544a65c3da90ea5bed437cce < 200 OK
Update the resource with a full representation
> PATCH /users/544a65c3da90ea5bed437cce < 200 OK
Update the resource with a partial representation
URL GRAMMARproperties as resources
> PATCH /orders/544a7455e5b3086ec8e55244 > ready=true
How do you mark an order as ready?
> POST /orders/ready > {"order": “544a7455e5b3086ec8e55244"} < 201 Created < Location: /orders/ready/544a7455e5b3086ec8e55244
How do you mark an order as ready?
> GET /orders/ready/544a7455e5b3086ec8e55244 > 302 Found < Location: /orders/544a7455e5b3086ec8e55244
URL GRAMMARproperties as resources
> GET /orders/ready/544a7455e5b3086ec8e55244 < 404 Not Found
Do you wanna know if an order is ready?
> DELETE /orders/ready/544a7455e5b3086ec8e55244 < 204 No Content
An order is not ready anymore?
An order is delivered? We would make sure that things remains consistent
> POST /orders/delivered > {"order": “544a7455e5b3086ec8e55244”} … > GET /orders/ready/544a7455e5b3086ec8e55244 < 404 Not Found
URL GRAMMARactions as resources
> POST /transaction/544a7455e5b3086ec8e55244/attempts < 201 Created < Location: /transaction/544a4bb6bdc88a12620eeb12
I want to retry a failed transaction
> POST /transaction/544a7455e5b3086ec8e55244/attempts < 409 Conflict
What would had happened if the transaction had already been completed?
URL GRAMMARactions as resources
> POST /scripts/run-every/10-minutes < 201 Created < Location: /cron/jobs/543e2e94559e343d1c1b3724
Run a script every 10 minutes: find a collection that represents the action
> POST /cron/jobs > {"script": "/script/path", "run-every": [10, "minutes"]} < 201 Created < Location: /cron/jobs/543e2e94559e343d1c1b3724
At least find a resource that is responsible of the action and give it the instructions
> POST /scripts/update-reports/schedule > {"run-every": [10, "minutes"]} < 200 OK
Do not simulate a custom action on the resource, this is not SOAP or OOP
URL GRAMMARbackground jobs as resources
> DELETE /subscription/543e0dd70fb5bf2b5a6680d2 < 202 Accepted
When a response could not be given synchronously, instead of…
> DELETE /subscription/543e0dd70fb5bf2b5a6680d2 < 202 Accepted < Location: /jobs/543e2e94559e343d1c1b3724
You can create a resource to let the process trackable
URL GRAMMARwhy is good?
•Ubiquitous Language •It’s easier to reason about • It’s easier to extend(Open Closed Principle)
QUESTIONS?