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
- (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
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
Cookie-based Authentication
RESTful Conversation Patterns
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
?
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