Modeling REST API Behaviour with Text, Graphics or Both?

TitleModeling REST API Behaviour with Text, Graphics or Both?
Publication TypeWorkshop Paper
Year of Publication2018
AuthorsIvanchikj, A., and C. Pautasso
WorkshopProc. of the 6th Workshop on Domain Specific Languages Design and Implementation (DSLDI 2018)
Place PublishedBoston, USA
Keywordsdsl, RESTalk

The dissemination of domain specific modeling languages in the software engineering world can be challenging as developers love to code and frequently look at graphical modeling as unnecessary and inefficient. This is less true when they are developing business facing software as the end users are non-technical people, and models become a common language to facilitate the communication with them, which explains the diffusion of modeling languages such as for example the Business Process Modeling Notation (BPMN). However, in Application Programming Interface (API) design, where both the creators and the users of the API are developers, the perceived benefits of modeling using a visual notation can be less evident for the developers. When developing APIs adhering to the REpresentation State Transfer (REST) architectural style, the documentation best practices of the structure of the API, i.e., the exposed resources and the HTTP methods that they support together with the corresponding media types, has been evolving in the past decade across a number of textual Domain Specific Languages (DSLs) currently being standardized within the Open API initiative. However, modeling the dynamics of the REST API showing the request-response interactions leading to conversations between clients and one or more resources exposed within the API is not yet a common practice. Thus, we have been working on designing RESTalk, a visual DSL for modeling RESTful conversations, i.e., sequences of client-server interactions aimed at achieving a certain goal. We have conducted a short exploratory survey where, regardless of the positive feedback on the usefulness of such a DSL and the cognitive characteristics of RESTalk, many of the respondents conditioned the adoption of the language to the existence of a suitable modeling tool. Faced with the challenge of developing such a tool, in this talk we would like to pinpoint a critical issue within the design space concerning the input modalities supported by a modeling tool tailored for RESTful APIs. Our goal is to encourage further discussions and empirical studies on what are the pros and cons of different approaches to modeling tools’ design and whether and how the targeted users of the modeling tool (e.g, business people, software architects, developers) affect the design choices.

Citation Key2018:restalk:dsldi
Refereed DesignationRefereed