RESTalk – a DSL for RESTful Conversations

RESTalk is a Domain Specific Modeling Language for visual representation of RESTful conversations. It is implemented as an extension of the Business Process Modeling Notation (BPMN) Choreography Diagrams with REST specific details. At its current version RESTalk only supports modelling of one to one RESTful conversations. Multiparty conversations will be supported in the future.

A legend of RESTalk is provided in the following figure:

image/svg+xml Request Response Request Hyperlink URI Hyperlink URI AlternativeResponse AlternativeResponse Exclusive XOR gateway Inclusive OR gateway Start event End event Sequence flow Hyperlink flow Client-Server Interaction Alternative Server Decisions RESTalk Parallel AND gateway Response timeout
Language elements of the RESTalk notation

The message content to be included in the client-server interaction shall contain, but is not limited to, the following details: HTTP method, URI, response status code and, where applicable, links.

A start and an end event are used to depict the beginning and the end of the conversation, while the timer event is used to model the response timeout due to server’s response taking too long, followed by the client resending the request. The timer can only be used attached to the request band, since it interrupts the normal request-response flow.

The sequence flow shows the flow of the conversation, while the hyperlink flow models URIs’ discovery nd usage by the client.

The gateways are used to diverge or converge different plausible conversation paths. They can be of different kind: parallel when concurrent paths are necessary, exclusive when only one of n paths is possible, and inclusive when any combination of the paths can occur.

The following figure shows an example of a generic conversation using RESTalk.

image/svg+xml Request Response Request Hyperlink1Hyperlink2 Hyperlink1 AlternativeResponse AlternativeResponse ResponseTimeout Hyperlink Flow Request Response Hyperlink2 2 3 4 7 6 1 5 8 8 8
Example of a RESTalk conversation

The client starts the conversation (1) by sending a request to which the server responds (2) with two hyperlinks which can be followed by the client (3) and which are related to the requested resource. The client can decide to follow just the first hyperlink or just the second hyperlink or both of them (4). If the server does not respond in time (6) to client’s request for the first hyperlink, the client can resend the request (5). The server can respond with one of the two alternatives (7) depending on the state of the requested resource. Once the response is received the conversation finishes (8).

RESTalk optional simplifications

To provide for the understandability of diagrams represented using RESTalk, the following simplifications and abstractions can be introduced.

  1. Although the client can end the conversation at any time, by simply not sending further requests, we use end events to model only the paths that result in the success or failure of the initial intent of the conversation.
  2. We only show the hyperlink flow of the last received response, while in reality the link could have been obtained earlier in the conversation as well.
  3. Due to the absence of consequences when resending idempotent requests, we only model the re- sending of non-idempotent requests (POST, PATCH) without emphasizing the fact that the client can eventually give up and stop resending the request.
  4. We also refrain from modeling alternative responses with 5xx status (server error) codes since they can occur after any request.

Getting started

As there is currently no editor or other tooling available, you can use this SVG file as starting point for modeling your own RESTful conversations.