URLs are not meant to be given to the clients but they should be discovered through the interaction with the server inside the representation of the resources. But thinking about URLs it's like thinking about names and relations between your domain resources. Creating a good URL grammar helps a good resource design. A good resource design is more stable and more extensible.

1. RESOURCE
ORIENTED
DESIGN
Gabriele Lana

2. WHAT IS REST?

3. WHAT IS… NOT
a Protocol
an Architecture
a Software
a Standard
another name for Web Services
a Buzzword

4. REST IS…
A Software Architectural Style,
a set of Constraints on Component
Interaction that, when obeyed,
cause the resulting Architecture to
have certain properties

5. 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”

6. Leonard Richardson & Sam Ruby
“RESTful Web Services”
O’Reilly 2007
DESIGN
RESTFUL
WEB
SERVICES
Step by Step

7. 1. EVERY
RESOURCE
MUST BE
IDENTIFIED

8. 2. DESIGN
THE
URLS

9. BAD
2. DESIGN
THE
URLS

10. URL GRAMMAR
collections, filters and selectors
/users/544a65c3da90ea5bed437cce
/conversion-rate/20141024
/conversion-rate/20141024..20141027
/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

11. URL GRAMMAR
aliases are good
Permanent alias
> GET /users/544a65c3da90ea5bed437cce
< 301 Moved Permanently
< Link: </users/544a65c3da90ea5bed437cce>; rel="canonical"
> GET /users/me
< 302 Found
< Location: /users/544a65c3da90ea5bed437cce
Depends on context
Depends on context
> GET /maps/here
< 200 Ok
< Link: </maps/lat/45.4557648/lon/9.0995368>; rel="canonical"

12. URL GRAMMAR
aliases are good
> GET /conversion-rate/yesterday
< 302 Found
< Location: /conversion-rate/20141027
Depends on time
Could hide complex but common queries
> GET /users/underage
< 302 Found
< Location: /users?age=(less-than-or-equal,18)

13. URL GRAMMAR
standard actions
Creates a new resource in the collection
> POST /users
< 201 Created
< Location: /users/544a65c3da90ea5bed437cce
> GET /users/544a65c3da90ea5bed437cce
< 200 OK
Show the resource
Remove the resource from the collection
What really means depends on the collection/resource
> DELETE /users/544a65c3da90ea5bed437cce
< 204 No Content

14. URL GRAMMAR
standard actions
Delete the login could mean to logout
> DELETE /login
< 301 Moved Permanently
< Set-Cookie: token=deleted; path=/; expires=…
< Location: /
Update the resource with a full representation
> PUT /users/544a65c3da90ea5bed437cce
< 200 OK
Update the resource with a partial representation
> PATCH /users/544a65c3da90ea5bed437cce
< 200 OK

15. URL GRAMMAR
properties as resources
How do you mark an order as ready?
> PATCH /orders/544a7455e5b3086ec8e55244
> ready=true
How do you mark an order as ready?
> POST /orders/ready
> {"order": “544a7455e5b3086ec8e55244"}
< 201 Created
< Location: /orders/ready/544a7455e5b3086ec8e55244
> GET /orders/ready/544a7455e5b3086ec8e55244
> 302 Found
< Location: /orders/544a7455e5b3086ec8e55244

16. URL GRAMMAR
properties as resources
Do you wanna know if an order is ready?
> GET /orders/ready/544a7455e5b3086ec8e55244
< 404 Not Found
An order is not ready anymore?
> DELETE /orders/ready/544a7455e5b3086ec8e55244
< 204 No Content
An order is delivered? We would make sure that things remains consistent
> POST /orders/delivered
> {"order": “544a7455e5b3086ec8e55244”}
…
> GET /orders/ready/544a7455e5b3086ec8e55244
< 404 Not Found

17. URL GRAMMAR
actions as resources
I want to retry a failed transaction
> POST /transaction/544a7455e5b3086ec8e55244/attempts
< 201 Created
< Location: /transaction/544a4bb6bdc88a12620eeb12
What would had happened if the transaction had already been completed?
> POST /transaction/544a7455e5b3086ec8e55244/attempts
< 409 Conflict

18. URL GRAMMAR
actions as resources
Run a script every 10 minutes: find a collection that represents the action
> POST /scripts/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 /cron/jobs
> {"script": "/script/path", "run-every": [10, "minutes"]}
< 201 Created
< Location: /cron/jobs/543e2e94559e343d1c1b3724
Do not simulate a custom action on the resource, this is not SOAP or OOP
> POST /scripts/update-reports/schedule
> {"run-every": [10, "minutes"]}
< 200 OK

19. URL GRAMMAR
background jobs as resources
When a response could not be given synchronously, instead of…
> DELETE /subscription/543e0dd70fb5bf2b5a6680d2
< 202 Accepted
You can create a resource to let the process trackable
> DELETE /subscription/543e0dd70fb5bf2b5a6680d2
< 202 Accepted
< Location: /jobs/543e2e94559e343d1c1b3724

20. URL GRAMMAR
why is good?
•Ubiquitous Language
•It’s easier to reason about
•It’s easier to extend
(Open Closed Principle)

22. QUESTIONS?