Software & Systems Modeling

, Volume 17, Issue 3, pp 1031–1051 | Cite as

Visual modeling of RESTful conversations with RESTalk

  • Ana Ivanchikj
  • Cesare Pautasso
  • Silvia Schreier
Regular Paper


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.


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



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


  1. 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)Google Scholar
  2. 2.
    Allweyer, T.: BPMN 2.0: Introduction to the Standard for Business Process Modeling. BoD–Books on Demand (2010)Google Scholar
  3. 3.
    Amundsen, M.: Building Hypermedia APIs with HTML5 and Node. O’Reilly, Sebastopol (2011)Google Scholar
  4. 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)Google Scholar
  5. 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)CrossRefGoogle Scholar
  6. 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)Google Scholar
  7. 7.
    Daniel, F., Matera, M.: Mashups: Concepts, Models and Architectures. Springer, Berlin (2014)CrossRefGoogle Scholar
  8. 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)Google Scholar
  9. 9.
    Fielding, R., Reschke, J.: Hypertext Transfer Protocol-HTTP/1.1. Request for Comments: 7230 (2014).
  10. 10.
    Fielding, R.T.: Architectural Styles and the Design of Network-Based Software Architectures. Ph.D. thesis, University of California, Irvine (2000)Google Scholar
  11. 11.
    Gemino, A., Wand, Y.: A framework for empirical evaluation of conceptual modeling techniques. Requir. Eng. 9(4), 248–260 (2004)CrossRefGoogle Scholar
  12. 12.
    Goteti, H.: API Driven Development, Bridging the Gap Between Providers and Consumers. Tech. rep., CA Technologies (2015).
  13. 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)CrossRefGoogle Scholar
  14. 14.
    Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., Orchard, D.: URI Template. Request for Comments: 6570 (2012).
  15. 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)Google Scholar
  16. 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)Google Scholar
  17. 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).
  18. 18.
    Hohpe, G.: Let’s have a conversation. IEEE Internet Comput. 11(3), 78–81 (2007)CrossRefGoogle Scholar
  19. 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)Google Scholar
  20. 20.
    Jensen, K.: Coloured Petri Nets: Basic Concepts, Analysis Methods and Practical Use, vol. 1. Springer, Berlin (2013)Google Scholar
  21. 21.
    Jordan, D., Evdemon, J.: Business Process Model And Notation (BPMN) Version 2.0. OMG (2011).
  22. 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)Google Scholar
  23. 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)Google Scholar
  24. 24.
    Lindland, O., Sindre, G., Solvberg, A.: Understanding quality in conceptual modeling. IEEE Softw. 11(2), 42–49 (1994)CrossRefGoogle Scholar
  25. 25.
    Masse, M.: REST API Design Rulebook. O’Reilly, Sebastopol (2011)Google Scholar
  26. 26.
    Mell, P., Grance, T.: The NIST Definition of Cloud Computing (2011)Google Scholar
  27. 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)Google Scholar
  28. 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)CrossRefGoogle Scholar
  29. 29.
    Newman, S.: Building Microservices. O’Reilly, Sebastopol (2015)Google Scholar
  30. 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)Google Scholar
  31. 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)Google Scholar
  32. 32.
    Nottingham, M.: Web Linking. Request for Comments: 5988 (2010).
  33. 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)Google Scholar
  34. 34.
    Petre, M.: UML in practice. In: Proceedings of the 2013 International Conference on Software Engineering (ICSE), pp. 722–731. IEEE Press (2013)Google Scholar
  35. 35.
    Rauf, I.: Design and Validation of Stateful Composite RESTful Web Services. Ph.D. thesis, Turku Centre for Computer Science (2014)Google Scholar
  36. 36.
    Richardson, L., Amundsen, M., Ruby, S.: RESTful Web APIs. O’Reilly, Sebastopol (2013)Google Scholar
  37. 37.
    Robillard, M.P.: What makes APIs hard to learn? Answers from developers. IEEE Softw. 26(6), 27–34 (2009)CrossRefGoogle Scholar
  38. 38.
    Robinson, S., Brooks, R., Kotiadis, K., Van Der Zee, D.J.: Conceptual Modeling for Discrete-Event Simulation. CRC Press, Boca Raton (2010)CrossRefzbMATHGoogle Scholar
  39. 39.
    Schermann, G., Cito, J., Leitner, P.: All the Services Large and Micro: Revisiting Industrial Practices in Services Computing. Tech. rep., PeerJ PrePrints (2015)Google Scholar
  40. 40.
    Schreier, S.: Modeling RESTful applications. In: Proceedings of the Second International Workshop on RESTful Design, pp. 15–21. ACM (2011)Google Scholar
  41. 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)Google Scholar
  42. 42.
    Taylor, R.N., Medvidovic, N., Dashofy, E.M.: Software Architecture: Foundations, Theory, and Practice. Wiley, New York (2009)CrossRefGoogle Scholar
  43. 43.
    van Porten, O.: Development and Evaluation of a Graphical Notation for Modelling Resource-Oriented Applications. Master’s thesis, FernUniversität, Hagen, Germany (2012)Google Scholar
  44. 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)Google Scholar
  45. 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. 46.
    Weske, M.: Business Process Management: Concepts, Languages, and Architectures, 2nd edn. Springer, Berlin (2012)CrossRefGoogle Scholar
  47. 47.
    Wohlin, C., Runeson, P., Höst, M., Ohlsson, M.C., Regnell, B., Wesslén, A.: Experimentation in Software Engineering. Springer, Berlin (2012)CrossRefzbMATHGoogle Scholar
  48. 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)Google Scholar
  49. 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

Copyright information

© Springer-Verlag Berlin Heidelberg 2016

Authors and Affiliations

  • Ana Ivanchikj
    • 1
  • Cesare Pautasso
    • 1
  • Silvia Schreier
    • 2
  1. 1.USILuganoSwitzerland
  2. 2.innoQ Deutschland GmbHMonheimGermany

Personalised recommendations