ECSA'15 - Modeling REST-ful conversations
•Download as PPTX, PDF•
4 likes•1,494 views
RESTful conversations are complex interactions between client(s) and server(s). Modelling them is important both for REST API designers and consumers. We believe that using efficient visualization tools to model the dynamics of a RESTful conversation and frequently used conversation patterns can improve teams’ productivity, promote reuse and leverage knowledge sharing. More details are available on the following link: http://design.inf.usi.ch/sites/default/files/biblio/2015_ECSA.pdf. Please contribute to our research and take our survey: http://restfulconversations.limequery.com/index.php/215135/lang-en
Recommended
More Related Content
Viewers also liked
Viewers also liked (18)
Similar to ECSA'15 - Modeling REST-ful conversations
Similar to ECSA'15 - Modeling REST-ful conversations (10)
Recently uploaded
Recently uploaded (20)
ECSA'15 - Modeling REST-ful conversations
- 1. Modeling RESTful Conversations with Extended BPMN Choreography Diagrams Cesare Pautasso, Ana Ivanchikj University of Lugano (USI) Switzerland Silvia Schreier innoQ Deutschland GmbH Germany European Conference on Software Architecture Cavtat, September 7-11 ECSA 2015
- 2. ana.ivanchikj@usi.ch RESTful conversation REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work ana.ivanchikj@usi.ch 2 Resource URI Resource URI Resource URI PUTURI reference create Link Relationships (Hypermedia)
- 3. ana.ivanchikj@usi.ch RESTful conversation REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work ana.ivanchikj@usi.ch 3 Resource URI Resource URI Resource URI PUTURI reference create Link Relationships (Hypermedia) 201Created
- 4. ana.ivanchikj@usi.ch 4 REST API structure - RAML REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 5. ana.ivanchikj@usi.ch 5 REST API structure- Swagger REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 6. ana.ivanchikj@usi.ch 6 GET /resource 1 HTTP/1.1 HTTP/1.1 303 See Other Location: /resource2 GET /resource2 HTTP/1.1 HTTP/1.1 200 OK REST API dynamics UML Sequence diagram BPMN Choreography diagram REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work - Redirect -
- 7. ana.ivanchikj@usi.ch BPMN Choreography 7 Inclusive gateway Parallel gateway REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Exclusive gateway
- 8. ana.ivanchikj@usi.ch 8 GET /resource 1 HTTP/1.1 HTTP/1.1 303 See Other Location: /resource2 GET /resource2 HTTP/1.1 HTTP/1.1 200 OK REST API dynamics UML Sequence diagram BPMN Choreography diagram Our proposal REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work - Redirect -
- 9. ana.ivanchikj@usi.ch Extended BPMN Choreography 9REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Assumption: ONE client – ONE server
- 10. ana.ivanchikj@usi.ch 10REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 11. ana.ivanchikj@usi.ch 11REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 12. ana.ivanchikj@usi.ch 12REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 13. ana.ivanchikj@usi.ch Long-running Request -RESTful Conversation Example- 13REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work e.g.: http://docs.aws.amazon.com/amazonglacier/latest/dev/job-operations.html
- 14. ana.ivanchikj@usi.ch Long-running Request - Happy path - 14 Create job POST / job HTTP/1.1 HTTP/1.1 202 Accepted Location: / job / 42 Poll GET / job / 42 HTTP/1.1 HTTP/1.1 200 OK Read results GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work GET / job / 42 HTTP/1.1 HTTP/1.1 303 See Other Location: / job / 42 / output
- 15. ana.ivanchikj@usi.ch Long-running Request - Resending the request - 15 Create job POST / job HTTP/1.1 Poll 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 Read results GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work HTTP/1.1 202 Accepted Location: / job / 42 POST / job HTTP/1.1
- 16. ana.ivanchikj@usi.ch Long-running Request - Reading the results - 16REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Create job POST / job HTTP/1.1 Poll 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 Read results GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK HTTP/1.1 202 Accepted Location: / job / 42 POST / job HTTP/1.1 GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK
- 17. ana.ivanchikj@usi.ch 17 Long-running Request - Deleting the output resource - Delete output DELETE / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Create job POST / job HTTP/1.1 Poll 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 Read results GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK HTTP/1.1 202 Accepted Location: / job / 42 POST / job HTTP/1.1 GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK
- 18. ana.ivanchikj@usi.ch 18 Long-running Request - Deleting the output resource - Delete output DELETE / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Create job POST / job HTTP/1.1 Poll 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 HTTP/1.1 202 Accepted Location: / job / 42 POST / job HTTP/1.1
- 19. ana.ivanchikj@usi.ch 19 Long-running Request Clean up DELETE / job / 42 HTTP/1.1 HTTP/1.1 200 OK REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Delete output DELETE / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK Create job POST / job HTTP/1.1 Poll 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 HTTP/1.1 202 Accepted Location: / job / 42 POST / job HTTP/1.1 - Deleting the job resource -
- 20. ana.ivanchikj@usi.ch 20 Long-running Request REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Create job POST / job HTTP/1.1 HTTP/1.1 202 Accepted Location: / job / 42 POST / job HTTP/1.1 Delete job DELETE / job / 42 HTTP/1.1 HTTP/1.1 200 OK - Deleting the job resource -
- 21. ana.ivanchikj@usi.ch Long-running Request 21REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 22. ana.ivanchikj@usi.ch Long-running Request - Short happy path - 22 Create job POST / job HTTP/1.1 HTTP/1.1 202 Accepted Location: / job / 42 Read results GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Poll GET / job / 42 HTTP/1.1 HTTP/1.1 303 See Other Location: / job / 42 / output
- 23. ana.ivanchikj@usi.ch 23 Long-running Request REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 24. ana.ivanchikj@usi.ch 24 Long-running Request - Long unhappy path - REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work Delete output DELETE / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK Create job POST / job HTTP/1.1 Read results GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK HTTP/1.1 202 Accepted Location: / job / 42 POST / job HTTP/1.1 GET / job / 42 / output HTTP/1.1 HTTP/1.1 200 OK Poll 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 HTTP/1.1 HTTP/1.1 200 OK Delete job DELETE / job / 42 HTTP/1.1 HTTP/1.1 200 OK
- 25. ana.ivanchikj@usi.ch Long-running Request -BPMN Choreography- 25REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 26. ana.ivanchikj@usi.ch 26 Long-running Request -Extended BPMN Choreography- REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 27. ana.ivanchikj@usi.ch Abstractions and Simplifications 27REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 28. ana.ivanchikj@usi.ch Abstraction – Server Error Response 28REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 29. ana.ivanchikj@usi.ch Abstraction – Idempotent requests 29REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 30. ana.ivanchikj@usi.ch Simplification – End events 30REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 31. ana.ivanchikj@usi.ch Simplification - Hyperlinks 31REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 32. ana.ivanchikj@usi.ch Simplifications and abstractions summary 32REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 33. ana.ivanchikj@usi.ch • Survey – Understandability – Ease of use Future Work • Conversation Patterns – Expressiveness – Collection – Reusability 33REST BPMN Choreography Extended BPMN Choreography Example Model Abstractions and Simplifications Future work
- 34. Contact us at: ana.ivanchikj@usi.ch c.pautasso@ieee.org silvia.schreier@innoq.com Contribute to our research by filling in the survey!!! http://restfulconversations.limequery.com/index.php/ 215135/lang-en
Editor's Notes
- Good afternoon everyone. I am Ana Ivanchikj and I am here to present the paper “Modeling RESTful Converseations with Extended BPMN Choreography Diagrams” written by Professor Cesare Pautasso and myself from the University of Lugano and in cooperation with Ms. Silvia Schreier from innoQ Germany.
- Very often the services offered by REST APIs require multiple request-response cycles between the client and the server thus becoming a RESTful conversation. The general topic discussed are resources hosted by the server and identified with unique uniform resource identifiers, but than the client decides which methods to call on such resources and the server decides what response to provide depending on the state of the resource. So for example when a client is looking up a resource URI the server can provide a reference link to another resource thus redirecting the client request. When retrieving the representation of the related resource the client can get the necessary links with the relation to create a new resource and finally make a request to create such resource. Thus RESTful conversations are dynamically driven by hypermedia and can take different directions.
- Very often the services offered by REST APIs require multiple request-response cycles between the client and the server thus becoming a RESTful conversation. The general topic discussed are resources hosted by the server and identified with unique uniform resource identifiers, but than the client decides which methods to call on such resources and the server decides what response to provide depending on the state of the resource. So for example when a client is looking up a resource URI the server can provide a reference link to another resource thus redirecting the client request. When retrieving the representation of the related resource the client can get the necessary links with the relation to create a new resource and finally make a request to create such resource. Thus RESTful conversations are dynamically driven by hypermedia and can take different directions.
- Existing REST API documentation tools such as RAML or
- Swagger refer to the static structure and expose low-level HTTP details which describe each available resource, the methods that can be called on the same, the representation format (such as JSON or XML) etc.
- However a RESTful conversation is not static, thus these tools do not support hypermedia links nor a concise visual representation of the dynamics of a particular conversation, i.e., all the interactions necessary to reach client’s final goal, a sort of a map to help clients explore the REST API. In a simple sequential conversation such as a redirect the order of the interaction is evident even from a simple table. Or we can use a UML Sequence diagram to present the dynamics where the client requests the first resource, gets a link to another resource as a response and uses it to send the second request. However it becomes messy to include details about the request verbs, headers, status codes etc. in a sequence diagram. Especially in conversations which are much more complex than a redirect and include multiple loops or end events, such as when traversing a collection of resources or in a long-running request as we will see later on. So we had the idea of using a standard BPMN Choreography, since after all its purpose is defining the order in which the exchange of messages occurs between different participants in business processes. Who is familiar with BPMN Choreography diagrams?
- It is a simple concept. The initiation of the conversation is marked with a start event. The main element is the BPMN activity comprised of an optional incoming/outgoing message with a text annotation to depict the message content and a three band choreography task containing the names of the conversation participants. Gateways are used to determine the path of the conversation, i.e., an exclusive gateway when the participants need to follow exactly one path, an inclusive gateway when the participants can choose to follow one or more paths, a parallel gateway when the participants need to follow all diverging paths. The end event is used to mark when the conversation is finished. However since the original domain of BPMN Choreography diagrams are business conversations between multiple business parties, the notation becomes cumbersome when describing RESTful conversations and the mandatory request -> response relationship is not that evident.
- Thus we propose certain extensions to the standard BPMN choreography diagram to make it REST specific.
- The main extension we propose is replacing the BPMN activity with a more compact two band request/response element with embedded message content. Since the participants in all RESTful interactions are always the client and the server we do not need to explicitly name them. This way the focus is on the content of the exchanged messages. We assume that there is always one client and one server in the conversation. Since in a RESTful interaction a request is always followed by a response, the request / response bends always go together,
- except when there is a path divergence due to different possible responses from the server to a given client’s request. In this case the request response bends are separated by an exclusive gateway to show the alternative responses that can be sent by the server.
- We propose changing the standard horizontal flow of the BPMN Choreography diagram with a vertical flow and adding a hyperlink flow element. This element indicates how URIs are discovered from hyperlinks embedded in the preceding response. The purpose is to clarify how clients discover and navigate among related resources.
- We propose using the timer event to model situations where the server takes too long to respond and thus the client decides to resend the request.
- In the next slides I will show a concrete example of a RESTful conversation regarding long-running requests modeled using the visual notation I have just presented. An example REST API using this conversation is Amazon Glacier’s API for long-term storage of infrequently used data. Retrieving such data can take between 3 and 5 hours.
- To avoid having the client waiting and experiencing network timeouts separate resources can be created for the job and the job output. The ideal path in this RESTful conversation would be the following: The conversation starts with a request which results with creating the job resource. Once the job has been created the client may poll the job resource to GET its current progress. If the job has not been completed yet, the client will get a 200 OK status and poll the status again later on. If the job has been completed the client gets redirected to another resource representing the output. Now that the client has the URI link to the job output it can request to read it. So this is the happy path. However as it often happens in life, the actual path is rarely the ideal happy path. The actual conversation can be much more complex.
- For instance the client might be impatient, and if the server does not reply soon enough it might resend the creation request until it gets the expected server response.
- Or the client might decide to read the output multiple times.
- Or to delete the output after reading it….
- or even before reading it.
- The conversation gets even longer if the client decides to do a clean up, i.e. delete the job resource as well. Or if we are dealing with a hesitant client
- it might decide to delete the job resource even before the output resource is created. Maybe because the body of its POST request was wrong.
- And this is as complicated as a long-running request can get. So as we can see with the proposed notation we can represent efficiently
- a very short happy path with no loops where the client immediately gets the job output and reads it,
- OR
- a very long unhappy path with multiple loops for creating the job or polling for its output and than doing the clean up. This shows the expressiveness of the proposed notation. It is enough to follow the arrows to discover all of the possible directions one conversation can take.
- Here is the same RESTful conversation modeled using the standard BPMN Choreography diagram. As we can see it is much more verbose, less concise and it looses the focus on the message content which is extremely important in REST APIs. So this diagram
- And this diagram actually model the same Long-running request conversation.
- As in every high-level conceptual modeling activity, if we do not introduce some simplifications and abstractions to the real model we might end up not seeing the forest for the trees. An example of a generic, not simplified RESTful conversation model could look like this.
- According to the HTTP protocol, it is always possible for an error to occur on the server, thus there is no need to show it explicitly.
- The client may choose to resend a request at any time if the server takes too long to respond. However we propose only modeling situations where the client decides to resend a non-idempotent request, such as POST. In this case resending the request twice might result with creating two resources when the goal was creating just one. Thus it is import to model how such situations are dealt with in a given REST API. We abstract from modeling the resending of idempotent requests.
- Due to the statelessness principle in REST, each client request is independent form the next request thus the client can decide at any time to stop sending requests. We propose simplifying the model by only modeling an end event after a response which completes in some way the initial goal of the client, and leaving out the other end events.
- And the last simplification refers to the hyperlinks. A client can make a request using any hyperlink it has discovered in the past. However to avoid too many lines or inevitable line crossings in more complex examples we propose just modeling the hyperlink from the last response that had disclosed it.
- After applying all of the proposed abstractions and simplifications regarding the server errors, resending of requests, unnecessary end events and hyperlinks, here is what the starting model would look like. As you can see it is much more concise and more readable, without loosing any important details.
- As future work we plan to conduct a survey among both designers of RESTful APIs and developers of client applications consuming them, to validate the understandability and ease of use of the proposed notation. We have also already started collecting and naming frequently used RESTful conversation patterns. We intend to explore how to compose together individual reusable patterns to simplify the modeling of larger conversations.
- Please contribute to our research by filling in the survey on the provided link. Or contact us if you have any patterns you would like to share with us or for any questions or suggestions you might have. To summarize, I have presented you our proposed notation for visual representation of the dynamics of a RESTful conversation, followed by a real world example of a model of the long-running request conversation and the simplifications used by the same. Thank you for your attention. Questions?