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?