XX:YY

Your browser doesn't support the features required by impress.js, so you are presented with a simplified version of this presentation.

For the best experience please use the latest Chrome, Safari or Firefox browser.

RESTful Conversation Patterns

Cesare Pautasso
http://www.pautasso.info
c.pautasso@ieee.org
@pautasso

A Pattern Language for RESTful Conversations

http://restalk-patterns.org

Cesare Pautasso @pautasso
Ana Ivanchikj @ivanchikj
Silvia Schreier @aivlis_s

[EuroPlop 2016]

Abstractions

Microservices

Interfaces

Conversations

Multiple interactions (message exchanges) between two or more participants
to achieve a goal

Gregor Hohpe

RESTful Conversations

Consuming RESTful APIs may involve multiple basic HTTP interactions

A client interacts with one or more resources, which may get dynamically discovered, created, updated and deleted

Some conversation patterns occur frequently

RESTful Conversations

Examples

?

GET /booking/42?payment HTTP/1.1
HTTP/1.1 302
Link: </payment?booking=42>; rel="payment"
GET /payment?booking=42 HTTP/1.1
HTTP/1.1 200

?

POST /slow HTTP/1.1
HTTP/1.1 202 Accepted
Location: /slow/42

...

GET /slow/42
HTTP/1.1 200

...

GET /slow/42
HTTP/1.1 303 See Other
Location: /result/42
GET /result/42
HTTP/1.1 200

?

GET /blog/42 HTTP/1.1
HTTP/1.1 200
Link: </blog/42/edit>; rel="edit"
GET /blog/42/edit HTTP/1.1
HTTP/1.1 200
Link: </blog/42>; rel="update"
PUT /blog/42 HTTP/1.1
HTTP/1.1 200 OK

RESTful Conversation

Servers control the conversation by embedding links into representations/responses

Clients drive the conversation by deciding which link to follow

Servers only reveal the immediate next steps

Clients need to understand the link relation semantics to choose which link to follow

RESTful Conversations

  1. Client/Server: Clients always begins every request-response interaction
  2. Requests are addressed to URI
  3. A request message is always followed by a response message, unless the server
    is not responding (connection refused)
    or not responsive (client timeout)
  4. There may be different possible responses to the same request message. The choice is entirely up to the server.
  1. Hypermedia: responses embed related URIs, which may be used to address subsequent requests
  2. Statelessness: every request is self-contained and therefore independent of the previous ones
  3. Uniform Interface: there is a fixed set of request methods a resource can support. Furthermore, it is possible to distinguish safe or idempotent requests from unsafe ones

How to Describe RESTful Conversations?

RESTalk

HTTP interaction

GET / HTTP/1.1
Host: restalk-patterns.org
HTTP/1.1 200 OK
Link: </patterns>; rel="list"

Sequential Conversation

GET / HTTP/1.1
HTTP/1.1 302 Found
Location: /blog
GET /blog HTTP/1.1
HTTP/1.1 200 OK
Link: </blog/add>; rel="add"
POST /blog/add HTTP/1.1
Slug: my post
HTTP/1.1 201 Created
Location: /blog/my-post/

Hyperlink Flow

Note: URIs in RESTalk diagrams are just placeholders

Branches and Loops

POST /job HTTP/1.1
HTTP/1.1 202 Accepted
Location: /job/42
GET /job/42 HTTP/1.1
HTTP/1.1 200 OK
GET /job/42 HTTP/1.1
HTTP/1.1 303 See Other
Location: /job/42/output
GET /job/42/output HTTP/1.1
HTTP/1.1 200 OK

RESTalk

Abstractions and Simplifications

RESTful Conversation Patterns

Patterns

Problems

Patterns

How to discover how to create a resource within a collection?

POST New Collection Item

Ask the server

POST New Collection Item

POST New Collection Item

Client discovers form with new resource attributes

Server determines new resource URI

Client must understand media type schema

What if the POST fails?

How to avoid creating duplicate resources?

POST-PUT Creation

POST Once Exactly

POST-PUT Creation

POST Once Exactly

What if the client times out because the server is taking too long to reply?

Long Running Operation with Polling

Long Running Operation with Polling

Long Running Operation with Polling

Clients can share the URI with the results

Clients can cancel the long running operation

Polling: how frequently?

Garbage collection

How to decouple clients from evolving resource URIs?

Server-side Redirection with Status Codes

Server-side Redirection with Status Codes

Server-side Redirection with Status Codes

Avoid breaking clients

Refer to server "nearest" to the client

Redirect can be temporary or permanent

Can your client be redirected any time?

Latency may increase

How to avoid hard-coding resource URIs into clients?

Client-side Navigation following Hyperlinks

Client-side Navigation following Hyperlinks

Client-side Navigation following Hyperlinks

Loose Coupling

Standardize Link Relation Semantics

Latency may increase

How to let a client retrieve some items of large collections?

Incremental Collection Traversal

Hypermedia

Incremental Collection Traversal

Incremental Collection Traversal

Save bandwidth

Cannot guarantee consistency

How to discover how to edit a resource?

(Partial) Resource Editing

(Partial) Resource Editing

(Partial) Resource Editing

Client discovers form with editable resource attributes

Idempotent full updates with PUT

Client must understand media type schema

PATCH is not idempotent

How to efficiently check if updates are possible?

Conditional Update for Large Resources

Declare client expectations

Conditional Update for Large Resources

Conditional Update for Large Resources

Save bandwidth, avoid bad requests

HTTP/1.1 Support Required
(otherwise 417 Expectation Failed)

Look Before You Leap

How to authenticate and authorize clients?

Protected Resources

Basic Authentication

Cookie-based Authentication

Basic Authentication

RESTful Conversation Patterns

Conclusion

References

Made with

http://asq.inf.usi.ch

?

GET /booking/42?payment HTTP/1.1
HTTP/1.1 302
Link: </payment?booking=42>; rel="payment"
GET /payment?booking=42 HTTP/1.1
HTTP/1.1 200

?

POST /booking HTTP/1.1
HTTP/1.1 201 Created
Location: /booking/42
GET /booking/42 HTTP/1.1
HTTP/1.1 200
ETag: v1
PUT /booking/42 HTTP/1.1
ETag: v1
HTTP/1.1 200

?

POST /slow HTTP/1.1
HTTP/1.1 202 Accepted
Location: /slow/42

...

GET /slow/42
HTTP/1.1 200

...

GET /slow/42
HTTP/1.1 303 See Other
Location: /result/42
GET /result/42
HTTP/1.1 200

Try-Confirm/Cancel (TCC)

Try to reserve multiple resources

POST /telephone HTTP/1.1
Host: api.swisscom.ch
HTTP/1.1 201 Created
Location: /telephone/0586664302
POST /bill HTTP/1.1
Host: api.post.ch
HTTP/1.1 201 Created
Location: /bill/42

If everything is successful, confirm the bookings

PUT /telephone/0586664302 HTTP/1.1
Host: api.swisscom.ch
Accept: application/tcc
HTTP/1.1 204 No Content
PUT /bill/42 HTTP/1.1
Host: api.post.ch
Accept: application/tcc
HTTP/1.1 204 No Content

Use a spacebar or arrow keys to navigate