Skip to main content

Visual modeling of RESTful conversations with RESTalk

Software & Systems Modeling volume 17, pages 1031–1051 (2018)Cite this article

Abstract

The cost savings introduced by Web services through code reuse and integration opportunities have motivated many businesses to develop Web APIs, with ever increasing numbers opting for the REST architectural style. RESTful Web APIs are decomposed in multiple resources, which the client can manipulate through HTTP interactions with well-defined semantics. Getting the resource in the desired state might require multiple client–server interactions, what we define as a RESTful conversation. RESTful conversations are dynamically guided by hypermedia controls, such as links. Thus, when deciding whether and how to use a given RESTful service, the client might not be aware of all the interactions which are necessary to achieve its goal. This is because existing documentation of RESTful APIs describes the static structure of the interface, exposing low-level HTTP details, while little attention has been paid to conceptual, high-level, modeling of the dynamics of RESTful conversations. Low-level HTTP details can be abstracted from during the design phase of the API, or when deciding which API to use. We argue that, in these situations, visual models of the required client–server interactions might increase developers’ efficiency and facilitate their understanding. Thus, to capture all possible interaction sequences in a given RESTful conversation, we propose RESTalk, an extension to the BPMN Choreography diagrams to render them more concise and yet sufficiently expressive in the specific REST domain. We also report on the results obtained from an exploratory survey we have conducted to assess the maturity of the field for a domain-specific language and to obtain feedback for future improvements of RESTalk.

This is a preview of subscription content, access via your institution.

Access options

Buy single article

Instant access to the full article PDF.

USD 39.95

Price includes VAT (USA)
Tax calculation will be finalised during checkout.

Fig. 1
Fig. 2
Fig. 3
Fig. 4
Fig. 5
Fig. 6
Fig. 7
Fig. 8
Fig. 9
Fig. 10
Fig. 11
Fig. 12
Fig. 13
Fig. 14
Fig. 15
Fig. 16
Fig. 17
Fig. 18
Fig. 19
Fig. 20
Fig. 21
Fig. 22
Fig. 23
Fig. 24
Fig. 25
Fig. 26

Notes

  1. http://www.programmableweb.com/protocol-api.

  2. http://raml.org.

  3. http://swagger.io.

  4. https://apiblueprint.org.

  5. https://www.mashape.com.

  6. This article includes and extends the work that the authors have presented at the 9th European Conference on Software Architecture (ECSA 2015) under the title “Modeling RESTful Conversations with Extended BPMN Choreography Diagrams” [33].

  7. http://restfulconversations.limequery.com.

  8. Since the questions were not mandatory a few industry participants did not answer all of them.

  9. http://docs.aws.amazon.com/amazonglacier/latest/dev/job-operations.html.

  10. N/A stands for persons who did not use any notation before and thus could not make the comparison.

  11. http://www.w3.org/2005/12/wscwg-charter.html.

  12. http://support.doodle.com/customer/en/portal/articles/664212-doodle-wizard-api.

References

  1. Alarcon, R., Wilde, E.: Linking Data from RESTful Services. In: Bizer, C., Heath, T., Berners-Lee, T., Hausenblas, M. (eds.) Third Workshop on Linked Data on the Web. Raleigh, North Carolina (2010)

  2. Allweyer, T.: BPMN 2.0: Introduction to the Standard for Business Process Modeling. BoD–Books on Demand (2010)

  3. Amundsen, M.: Building Hypermedia APIs with HTML5 and Node. O’Reilly, Sebastopol (2011)

    Google Scholar 

  4. Barros, A., Dumas, M., ter Hofstede, A.H.: Service interaction patterns. In: van der Aalst, W.M.P., Benatallah, B., Casati, F., Curbera, F. (eds.) Business Process Management, LNCS, vol. 3649, pp. 302–318. Springer, Berlin (2005)

  5. Benatallah, B., Casati, F., et al.: Web service conversation modeling: a cornerstone for e-business automation. IEEE Internet Comput. 8(1), 46–54 (2004)

    Article  Google Scholar 

  6. Cortes-Cornax, M., Dupuy-Chessa, S., Rieu, D., Dumas, M.: Evaluating choreographies in BPMN 2.0 using an extended quality framework. In: Dijkman, R., Hofstetter, J., Koehler, J. (eds.) Business Process Model and Notation, LNBIP, vol. 95, pp. 103–117. Springer, Berlin (2011)

  7. Daniel, F., Matera, M.: Mashups: Concepts, Models and Architectures. Springer, Berlin (2014)

    Book  Google Scholar 

  8. Decker, G., Barros, A.: Interaction modeling using BPMN. In: ter Hofstede, A., Benatallah, B., Paik, H.Y. (eds.) Business Process Management Workshops, LNCS, vol. 4928, pp. 208–219. Springer, Berlin (2008)

  9. Fielding, R., Reschke, J.: Hypertext Transfer Protocol-HTTP/1.1. Request for Comments: 7230 (2014). https://tools.ietf.org/html/rfc7230

  10. Fielding, R.T.: Architectural Styles and the Design of Network-Based Software Architectures. Ph.D. thesis, University of California, Irvine (2000)

  11. Gemino, A., Wand, Y.: A framework for empirical evaluation of conceptual modeling techniques. Requir. Eng. 9(4), 248–260 (2004)

    Article  Google Scholar 

  12. Goteti, H.: API Driven Development, Bridging the Gap Between Providers and Consumers. Tech. rep., CA Technologies (2015). http://rewrite.ca.com/us/articles/application-economy/apis-bridging-the-gap-between-providers-and-consumers.html

  13. Green, T.R.G., Petre, M.: Usability analysis of visual programming environments: a cognitive dimensions framework. J. Vis. Lang. Comput. 7(2), 131–174 (1996)

    Article  Google Scholar 

  14. Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., Orchard, D.: URI Template. Request for Comments: 6570 (2012). https://tools.ietf.org/html/rfc6570

  15. Haupt, F., Karastoyanova, D., Leymann, F., Schroth, B.: A model-driven approach for REST compliant services. In: International Conference on Web Services (ICWS 2014), pp. 129–136. IEEE (2014)

  16. Haupt, F., Leymann, F., Pautasso, C.: A conversation based approach for modeling REST APIs. In: Proceedings of the 12th WICSA 2015. Montreal, Canada (2015)

  17. Hickson, I., Berjon, R., Faulkner, S., Leithead, T., Navara, E., OConnor, E., Pfeiffer, S.: HTML5. A vocabulary and associated APIs for HTML and XHTML. W3C Recommendation (2014). http://www.w3.org/TR/html5/forms.html

  18. Hohpe, G.: Let’s have a conversation. IEEE Internet Comput. 11(3), 78–81 (2007)

    Article  Google Scholar 

  19. Ivanchikj, A.: RESTful conversation with RESTalk—the use case of doodle. In: Proceedings of the International Conference on Web Engineering (ICWE’16), pp. 583–587. Springer, Berlin (2016)

  20. Jensen, K.: Coloured Petri Nets: Basic Concepts, Analysis Methods and Practical Use, vol. 1. Springer, Berlin (2013)

    Google Scholar 

  21. Jordan, D., Evdemon, J.: Business Process Model And Notation (BPMN) Version 2.0. OMG (2011). http://www.omg.org/spec/BPMN/2.0/

  22. Li, L., Chou, W.: Design and Describe REST API Without Violating REST: A Petri Net Based Approach. In: 2011 IEEE International Conference on Web Services (ICWS), pp. 508–515 (2011)

  23. Li, L., Chou, W.: Designing Large Scale REST APIs Based on REST Chart. In: 2015 IEEE International Conference on Web Services (ICWS), pp. 631–638 (2015)

  24. Lindland, O., Sindre, G., Solvberg, A.: Understanding quality in conceptual modeling. IEEE Softw. 11(2), 42–49 (1994)

    Article  Google Scholar 

  25. Masse, M.: REST API Design Rulebook. O’Reilly, Sebastopol (2011)

    Google Scholar 

  26. Mell, P., Grance, T.: The NIST Definition of Cloud Computing (2011)

  27. Mitra, R.: Rapido: a sketching tool for Web API designers. In: Proceedings of the 24th International Conference on World Wide Web. WWW ’15 Companion, pp. 1509–1514. Florence, Italy (2015)

  28. Moody, D.: The “Physics” of notations: toward a scientific basis for constructing visual notations in software engineering. IEEE Trans. Softw. Eng. 35(6), 756–779 (2009)

    Article  Google Scholar 

  29. Newman, S.: Building Microservices. O’Reilly, Sebastopol (2015)

    Google Scholar 

  30. Nikaj, A., Mandal, S., Pautasso, C., Weske, M.: From choreography diagrams to RESTful interactions. In: The Eleventh International Workshop on Engineering Service-Oriented Applications, pp. 3–14 (2015)

  31. Nikaj, A., Weske, M.: Formal specification of RESTful choreography properties. In: Proceedings of the International Conference on Web Engineering (ICWE’16), pp. 365–372. Springer, Berlin (2016)

  32. Nottingham, M.: Web Linking. Request for Comments: 5988 (2010). https://tools.ietf.org/html/rfc5988

  33. Pautasso, C., Ivanchikj, A., Schreier, S.: Modeling RESTful conversations with extended BPMN choreography diagrams. In: Weyns, D., Mirandola, R., Crnkovic, I. (Eds.) European Conference on Software Architecture, LNCS, pp. 87–94. Springer, Berlin (2015)

  34. Petre, M.: UML in practice. In: Proceedings of the 2013 International Conference on Software Engineering (ICSE), pp. 722–731. IEEE Press (2013)

  35. Rauf, I.: Design and Validation of Stateful Composite RESTful Web Services. Ph.D. thesis, Turku Centre for Computer Science (2014)

  36. Richardson, L., Amundsen, M., Ruby, S.: RESTful Web APIs. O’Reilly, Sebastopol (2013)

    Google Scholar 

  37. Robillard, M.P.: What makes APIs hard to learn? Answers from developers. IEEE Softw. 26(6), 27–34 (2009)

    Article  Google Scholar 

  38. Robinson, S., Brooks, R., Kotiadis, K., Van Der Zee, D.J.: Conceptual Modeling for Discrete-Event Simulation. CRC Press, Boca Raton (2010)

    Book  MATH  Google Scholar 

  39. Schermann, G., Cito, J., Leitner, P.: All the Services Large and Micro: Revisiting Industrial Practices in Services Computing. Tech. rep., PeerJ PrePrints (2015)

  40. Schreier, S.: Modeling RESTful applications. In: Proceedings of the Second International Workshop on RESTful Design, pp. 15–21. ACM (2011)

  41. Steiner, T., Algermissen, J.: Fulfilling the Hypermedia Constraint Via HTTP OPTIONS, the HTTP Vocabulary In RDF, And Link Headers. In: Proceedings of the Second International Workshop on RESTful Design, pp. 11–14. ACM (2011)

  42. Taylor, R.N., Medvidovic, N., Dashofy, E.M.: Software Architecture: Foundations, Theory, and Practice. Wiley, New York (2009)

    Book  Google Scholar 

  43. van Porten, O.: Development and Evaluation of a Graphical Notation for Modelling Resource-Oriented Applications. Master’s thesis, FernUniversität, Hagen, Germany (2012)

  44. Verborgh, R., Hausenblas, M., Steiner, T., Mannens, E., Van de Walle, R.: Distributed affordance: an open-world assumption for hypermedia. In: Proceedings of the 4th International Workshop on RESTful Design, pp. 1399–1406. ACM (2013)

  45. Völter, M., Kircher, M., Zdun, U.: Remoting Patterns: Foundations of Enterprise, Internet and Realtime Distributed Object Middleware. Wiley, New York (2013)

    Google Scholar 

  46. Weske, M.: Business Process Management: Concepts, Languages, and Architectures, 2nd edn. Springer, Berlin (2012)

    Book  Google Scholar 

  47. Wohlin, C., Runeson, P., Höst, M., Ohlsson, M.C., Regnell, B., Wesslén, A.: Experimentation in Software Engineering. Springer, Berlin (2012)

    Book  MATH  Google Scholar 

  48. Zaha, J.M., Barros, A., et al.: Let’s dance: a language for service behavior modeling. In: On the Move to Meaningful Internet Systems 2006: CoopIS, DOA, GADA, and ODBASE, pp. 145–162. Springer, Berlin (2006)

  49. Zuzak, I., Budiselic, I., Delac, G.: A finite-state machine approach for modeling and analyzing RESTful systems. J. Web Eng. 10(4), 353–390 (2011)

    Google Scholar 

Download references

Acknowledgments

We would like to thank all of the participants in the survey and the anonymous reviewers for their time and valuable feedback.

Author information

Authors and Affiliations

  1. USI, Lugano, Switzerland

    Ana Ivanchikj & Cesare Pautasso

  2. innoQ Deutschland GmbH, Monheim, Germany

    Silvia Schreier

Authors
  1. Ana Ivanchikj
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Cesare Pautasso
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Silvia Schreier
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to Ana Ivanchikj.

Additional information

Communicated by Prof. Antonio Vallecillo.

Rights and permissions

Reprints and Permissions

About this article

Verify currency and authenticity via CrossMark

Cite this article

Ivanchikj, A., Pautasso, C. & Schreier, S. Visual modeling of RESTful conversations with RESTalk. Softw Syst Model 17, 1031–1051 (2018). https://doi.org/10.1007/s10270-016-0532-2

Download citation

  • Received:

  • Revised:

  • Accepted:

  • Published:

  • Issue Date:

  • DOI: https://doi.org/10.1007/s10270-016-0532-2

Keywords

  • RESTful Web services
  • Conversations
  • BPMN Choreography
  • Modeling notation extension
  • Exploratory study
  • Domain-specific language
  • Questionnaire
  • RESTalk