RESTful Conversation Patterns

Cesare Pautasso
http://www.pautasso.info
[email protected]
@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

Structure
Behavior

(WSDL)
WADL
RAML
OpenAPI (Swagger)

UML Sequence Diagrams
UML Activity Diagrams
BPMN
RESTalk

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

Link: </payment?booking=42>; rel="payment"

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

Client/Server: Clients always begins every request-response interaction
Requests are addressed to URI
A request message is always followed by a response message, unless the server
is not responding (connection refused)
or not responsive (client timeout)
There may be different possible responses to the same request message. The choice is entirely up to the server.

Hypermedia: responses embed related URIs, which may be used to address subsequent requests
Statelessness: every request is self-contained and therefore independent of the previous ones
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

Describe how URIs are discovered during the conversation
URI found in responses flow into URIs used in following requests

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

Servers may always fail
Clients may always retry idempotent requests
Clients may stop at any time
Clients only remember the last response

RESTful Conversation Patterns

Resource Creation
Resource Discovery
Resource Editing
Resource Protection

Patterns

Problems

Resource Creation
- How to discover how to create a resource within a collection?
- How to avoid duplicates?
- How to deal with client timeouts for long running operations?
Resource Discovery
- How to tell the client the URI has changed?
- How to let a client dynamically discover URIs?
- How to let a client retrieve all items of large collections?
Resource Editing
- How to discover how to edit a resource?
- How to efficiently check if updates are possible?
Resource Protection
- How to perform client authentication?
- How to enforce access control?

Patterns

Resource Creation
- POST New Collection Item
- POST Once Exactly
- POST-PUT Creation
- Long Running Operation with Polling
Resource Discovery
- Server-side Redirection with Status Codes
- Client-side Navigation following Hyperlinks
- Incremental Collection Traversal
Resource Editing
- (Partial) Resource Editing
- Conditional Update for Large Resources
Resource Protection
- Basic Authentication
- Cookies-based Authentication

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

POST New Collection Item

Ask the server

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

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

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

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

Save bandwidth

Cannot guarantee consistency

How to discover how to edit a resource?

(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

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

Cookie-based Authentication

RESTful Conversation Patterns

http://restalk-patterns.org

Conclusion

RESTful architectures are full of conversations enabled by hyperlinks embedded in resource representations
RESTalk visualizes conversations: modeling all possible request-response interactions and the hyperlink flow linking them
Let us know if you spot some of the patterns in your RESTful API

References

Cesare Pautasso, Ana Ivanchikj, and Silvia Schreier, A Pattern Language for RESTful Conversations, EuroPlop 2016 (to appear)
Ana Ivanchikj, Cesare Pautasso, and Silvia Schreier, Visual modeling of RESTful conversations with RESTalk, Journal of Software & Systems Modeling, pp. 1-21, May, 2016.
F. Haupt, F. Leymann, C. Pautasso: A conversation based approach for modeling REST APIs, 12th Working IEEE / IFIP Conference on Software Architecture (WICSA 2015), Montreal, CA, May 2015
G. Hohpe, RESTful Conversations, 15 March 2015
AirBNB, What does each reservation status mean?
G. Hohpe, "Let's have a conversation", Internet Computing, IEEE 11.3 (2007): 78-81.
Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures, University of California, Irvine, 2000
G. Pardon and C. Pautasso, Atomic Distributed Transactions: a RESTful Design, 5th International Workshop on Web APIs and RESTful Design (WS-REST), Seoul, Korea, ACM, April, 2014.
Jim Webber, Savas Parastatidis, Ian Robinson, REST in Practice: Hypermedia and Systems Architecture, O'Reilly, 2010
R. Verborgh, M. Hausenblas, T. Steiner, E. Mannens, and R. van de Walle, "Distributed affordance: An open-world assumption for hypermedia", Proceedings of the Fourth International Workshop on RESTful Design (WS-REST), 2013.
Cesare Pautasso, Erik Wilde, Push-Enabling RESTful Business Processes, 9th International Conference on Service Oriented Computing (ICSOC 2011), Paphos, Cyprus, December 2011
Cesare Pautasso, BPMN for REST, In Proceedings of the 3rd International Workshop on BPMN (BPMN 2011), Lucerne, Switzerland, November 2011
Thomas Erl, Benjamin Carlyle, Cesare Pautasso, Raj Balasubramanian, SOA with REST: Principles, Patterns & Constraints for Building Enterprise Solutions with REST, Prentice Hall, 2012

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