Keywords

1 Introduction

The idea behind the Representational State Transfer (REST) architectural style is to introduce simplicity through constraints and standardization. This has inevitably brought about its popularity, with an ever-growing number of Web Application Program Interfaces (APIs) declaring REST compliance. While the awareness for the need of documenting the low-level HTTP details of REST API’s static structure has resulted with several tools, such as RAML or SwaggerFootnote 1, there is still a lack of support for conceptual modeling and visualisation of REST API’s dynamics. Reaching a certain resource state, frequently requires undertaking a predefined sequence of interactions or choosing among different alternative paths, thus shifting from the concept of a single RESTful interaction to the concept of a RESTful conversation [1]. As conversations become more complex, visualising them can help decrease the cognitive load of API designers, who need to communicate their design to the developers, or of API clients, who need to use the API. Currently, mainly UML Sequence Diagrams or UML State Machines are used to model API’s behaviour. However, they lack the ability of concisely presenting important REST tenets, such as HTTP methods, URIs, headers, hypermedia flow, status codes, etc.

Therefore, in [2] we have proposed the first version of RESTalk, a Domain Specific Language (DSL) for modeling RESTful conversations. In [3] we have conducted an exploratory survey, among practitioners and researchers, to obtain initial feedback on its cognitive characteristics, and its perceived usefulness. In this poster paper, based on the survey feedback, we extend RESTalk with additional language constructs to support modelling of multiple participants in the conversation and their roles, as well as to present resource state transitions, and asynchronous email communication. We use this extended version of RESTalk to model the behaviour of Doodle, a well known scheduling Web serviceFootnote 2 which depicts RESTful conversations between multiple clients and one server.

2 RESTalk

To model RESTful interactions, Nikaj and Weske [4] add REST-specific annotations to the Choreography diagram of the Business Process Model and Notation (BPMN) 2.0 standard. With RESTalk we go further and modify the standard notation in order to visually draw the attention to what is essential in RESTful interactions, i.e., the content of the exchanged messages.

The results from the above mentioned exploratory survey [3], have revealed missing constructs in RESTalk for depicting: 1) roles of the conversation participants, when viable interactions depend on such roles; 2) multiparty conversations where multiple clients interact with the server; 3) client-server interactions which lead to changes in the related resource’s state; and 4) asynchronous interaction through email notifications sent to participants. Thus, in this poster paper, we propose a way to extend RESTalk to represent such important details. Figure 1 shows a summary of all the language constructs relevant to the Doodle use case which we will describe in Sect. 3. The semantics of the existing RESTalk constructs, i.e., the ones not added to the language with this poster paper, are explained in detail in [2].

Fig. 1.
figure 1

RESTalk Constructs

Full size image

3 The Doodle Use Case

To show-case the appropriateness of RESTalk for documenting real RESTful APIs, we have decided to use it to model Doodle’s API. Doodle’s basic free offering is a Web service which facilitates event scheduling between multiple participants. We have opted for modeling this basic service, where no log-in is required. Due to the lack of detailed API documentationFootnote 3, we have used a prescriptive instead of descriptive approach in modeling its dynamics.

Fig. 2.
figure 2

Doodle RESTful conversation with RESTalk

Full size image

Following is the natural language description of the conversation modelled in Fig. 2. The client can take two distinct roles leading to different privileges. The admin role, assigned to the client who has created the poll, and the participant role, assigned to the clients who are invited to participate in the poll. After the admin creates the poll, emails are sent to the admin, with a link to the poll resource, and to all participants, with a link to the poll voting resource. The poll can have three states: active, closed, or deleted. The interaction which results with entering in a certain state is marked with a dashed line and the state variable is noted under the response box. The admin can edit, close or delete the poll at any time, as well as reactivate it if closed. When the poll is closed, an email notification may be sent to the participants. The participants can only vote, change or delete their votes when the poll is active, resulting with an email being sent to the admin. If the poll is closed, the participants can only see the results, without editing them. If the poll is deleted, they get an error message.

4 Related Work

Although the existing work on modeling RESTful APIs distinguishes between the need of modeling both the static and dynamic aspects of these APIs [5], the focus has mainly remained on the static aspect. When tackled, REST API’s dynamics has been mostly analysed from the resource state transition perspective [6, 7]. We add another perspective to the dynamics, i.e., the client-server interactions necessary to initiate such state transitions. To visualise them, we have designed and work on improving RESTalk, a DSL for modeling RESTful conversations.

5 Conclusions and Future Work

It is rarely possible to follow a waterfall approach when designing a DSL, as evidenced by the continuous release of new versions of many standard languages. Each DSL keeps on evolving as its domain is evolving, and as users provide feedback on identified gaps in the language, or situations which can not be reliably modeled with it. RESTalk is not an exception to this practice, and we support the agile approach in language design with frequent iterations. Thus, in this poster paper, we extend RESTalk based on recently acquired survey feedback and showcase the appropriateness of using such extended version for modeling the Doodle API. Further extensions are planned to develop a version complete enough to be launched for testing in industry. In the future the notation could be supported with a multi-view editor and a tool for automatic code generation.