models'16 - restalk

Visual Modeling of RESTful Conversa6ons with RESTalk

Ana Ivanchikj, Cesare Pautasso Università della Svizzera italiana (USI)

Lugano, Switzerland

Silvia Schreier innoQ Deutschland GmbH

Monheim, Germany

MOTIVATION

2

What is a RESTful conversa6on? Why do we need a Domain Specific Language to model it?

3

RESTful conversa6on

Resource

URI

Resource

URI

Resource

URI

PUT U

RI reference create

Link Rela6onships (Hypermedia)

RESTful Conversa=ons è REST API Structure è REST API dynamics

Mo=va=on è RESTalk è RESTalk Exploratory Survey è Conclusions

4

RESTful conversa6on

Resource

URI

Resource

URI

Resource

URI

PUT U

RI reference create

Link Rela6onships (Hypermedia) 201 Created


RESTful Conversa=ons è REST API Structure è REST API dynamics

5

REST API structure -‐ RAML Mo=va=on è RESTalk è RESTalk Exploratory Survey è Conclusions

RESTful Conversa6ons è REST API Structure è REST API dynamics

6

REST API structure-‐ Swagger Mo=va=on è RESTalk è RESTalk Exploratory Survey è Conclusions


7

GET /resource 1 HTTP/1.1

HTTP/1.1 303 See Other Loca6on: /resource2

GET /resource2 HTTP/1.1

HTTP/1.1 200 OK

GET /resource1

Client

Server

303 See OtherLocation:/resource2

GET /resource2

Client

Server

200 OK

REST API dynamics

UML Sequence diagram BPMN Choreography diagram RESTalk

GET /resource1

303 See OtherLocation: /resource2

GET /resource2

200 OK

-‐ Redirect -‐



RESTalk

8

RESTalk constructs Long-‐running request modeled with RESTalk

9

Start event

End event

Timer event

Sequence flowHyperlink flow

Exclusive XOR gateway

Inclusive OR gateway

Parallel AND gateway

Request

ResponseHyperlink URI

Client-Server Interaction

RESTalk Mo6va6on è RESTalk è RESTalk Exploratory Survey è Conclusions

RESTalk Constructs è RESTalk Show-‐Case

Events

Flows

Gateways

RequestHyperlink URI

AlternativeResponse

AlternativeResponse

Alternative Server Responses

Long-‐running Request -‐RESTful Conversa6on Paeern Example-‐

-‐Visualized with RESTalk-‐

10

e.g.: hep://docs.aws.amazon.com/amazonglacier/latest/dev/job-‐opera6ons.html

Mo6va6on è RESTalk è RESTalk Exploratory Survey è Conclusions


Long-‐running Request -‐ Happy path -‐

11

Create job POST / job HTTP/1.1

HTTP/1.1 202 Accepted Loca6on: / job / 42

Poll GET / job / 42 HTTP/1.1

HTTP/1.1 200 OK

Read results GET / job / 42 / output HTTP/1.1

HTTP/1.1 200 OK

GET / job / 42 HTTP/1.1

HTTP/1.1 303 See Other Loca6on: / job / 42 / output

POST /job

202 AcceptedLocation: /job/42

GET /job/42/output

200 OK

GET /job/42

200 OK 303 See OtherLocation: /job/42/output

GET /job/42/output

200 OK



Long-‐running Request -‐ Resending the request -‐

12



HTTP/1.1 200 OK




HTTP/1.1 200 OK


POST / job HTTP/1.1 POST /job


GET /job/42/output

200 OK

GET /job/42


GET /job/42/output

200 OK



-‐ Reading the results -‐

13



HTTP/1.1 200 OK




HTTP/1.1 200 OK


POST / job HTTP/1.1

GET / job / 42 / output HTTP/1.1

HTTP/1.1 200 OK

POST /job


GET /job/42/output

200 OK

GET /job/42


GET /job/42/output

200 OK



Long-‐running Request

14

-‐ Dele6ng the output resource -‐

Delete output DELETE / job / 42 / output HTTP/1.1

HTTP/1.1 200 OK



HTTP/1.1 200 OK




HTTP/1.1 200 OK


POST / job HTTP/1.1


HTTP/1.1 200 OK

DELETE /job/42/output

200 OK

POST /job


GET /job/42/output

200 OK

GET /job/42


GET /job/42/output

200 OK




15

-‐ Dele6ng the output resource -‐


HTTP/1.1 200 OK



HTTP/1.1 200 OK




POST / job HTTP/1.1


200 OK

POST /job


GET /job/42/output

200 OK

GET /job/42


GET /job/42/output

200 OK




16

Clean up DELETE / job / 42 HTTP/1.1

HTTP/1.1 200 OK


HTTP/1.1 200 OK



HTTP/1.1 200 OK




POST / job HTTP/1.1

-‐ Dele6ng the job resource -‐


200 OK

GET /job/42/output

200 OK

GET /job/42


GET /job/42/output

200 OK

DELETE /job/42

200 OK

POST /job





17



POST / job HTTP/1.1

Delete job DELETE / job / 42 HTTP/1.1

HTTP/1.1 200 OK

-‐ Dele6ng the job resource -‐


200 OK

GET /job/42/output

200 OK

GET /job/42


GET /job/42/output

200 OK

DELETE /job/42

200 OK

POST /job





18

POST /job



200 OK

DELETE /job/42

200 OKGET /job/42


GET /job/42/output

200 OK




-‐ Short happy path -‐

19




HTTP/1.1 200 OK



POST /job



200 OK

DELETE /job/42

200 OKGET /job/42


GET /job/42/output

200 OK




20

POST /job



200 OK

DELETE /job/42

200 OKGET /job/42


GET /job/42/output

200 OK




21

-‐ Long path -‐


HTTP/1.1 200 OK



HTTP/1.1 200 OK


POST / job HTTP/1.1


HTTP/1.1 200 OK


HTTP/1.1 200 OK




HTTP/1.1 200 OK

Delete job DELETE / job / 42 HTTP/1.1

HTTP/1.1 200 OK

POST /job



200 OK

DELETE /job/42

200 OKGET /job/42


GET /job/42/output

200 OK




RESTalk Exploratory Survey

22

Mo6va6on Goals Design Results

23

RESTalk Use

Survey Experiment

Feedback implementa6on

Final Goal: Increase acceptance and dissemina4on of RESTalk

Approach: Agile DSML Design Mo6va6on è RESTalk è RESTalk Exploratory Survey è Conclusions

Mo=va=on è Goals è Design è Results

24

•  Goal 1: Evaluate the need in industry for a domain specific language for modeling RESTful conversa6ons

Explora6ve Survey Goals

*Qualita=ve research technique => No sta=s=cal inference


Mo6va6on è Goals è Design è Results

•  Goal 2: Evaluate the cogni6ve characteris6cs of RESTalk

25

Mainly open ended op6onal ques6ons

Explora6ve Survey Design English + German

7 ques6on groups: -‐  demographic data -‐  background on used

nota6ons in prac6ce -‐  RESTalk’s intui6veness -‐  RESTalk vs. standard

BPMN Choreography -‐  reading task -‐  modeling task -‐  RESTalk’s evalua6on



26

8"

10"

7"

6"

4"

9" 9"

6"

7"

4"

0%"

5%"

10%"

15%"

20%"

25%"

30%"

Up"to"1"year"

1"to3"years"

3"to"5"years"

5"to"7"years"

more"than"7"years"

Developing"APIs"

Using"APIs"

35 respondents: -‐ 74% industry -‐ 26% academia

Profile: -‐ IT consultants -‐ SW quality engineers -‐ SW developers -‐ SW architects -‐ a CTO -‐ researchers

Respondents’ Demographic Data Mo6va6on è RESTalk è RESTalk Exploratory Survey è Conclusions


27

54%$

85%$

8%$

31%$

15%$

0%$

10%$

20%$

30%$

40%$

50%$

60%$

70%$

80%$

90%$

UML$Ac2vity$Diagram$

UML$Sequence$Diagram$

BPMN$Choreography$

InIhouse$developed$

Other$standard$nota2on$

Used nota6ons in prac6ce -‐38% of respondents-‐



28

POST /resource<empty>

201 CreatedLocation: /resource/X

PUT /resource/X<content>

200 OK

RESTalk’s intui6veness ?

?



67%$ 67%$70%$

87%$

100%$

0%$

20%$

40%$

60%$

80%$

100%$

120%$

Up$to1$year$ 1$to$3$years$ 3$to$5$years$ 5$to$7$years$ more$than$7$years$

The$goal$of$this$RESTful$conversaCon$is$creaCng$a$new$resource$

The$client$can$send$the$POST$request$mulCple$Cmes$

By$sending$mulCple$POST$requests$mulCple$resources$are$being$created$

The$client$knows$the$link$to$the$created$resource$before$the$start$of$the$conversaCon$

Average$correct$answers$

67%$ 67%$70%$

87%$

100%$

0%$

20%$

40%$

60%$

80%$

100%$

120%$







29

POST /resource<empty>

201 CreatedLocation: /resource/X

PUT /resource/X<content>

200 OK

67%$ 67%$70%$

87%$

100%$

0%$

20%$

40%$

60%$

80%$

100%$

120%$







RESTalk’s intui6veness Mo6va6on è RESTalk è RESTalk Exploratory Survey è Conclusions


30

Request

Response

Request

Hyperlink1 URIHyperlink2 URI

Hyperlink1 URI

AlternativeResponse

AlternativeResponse

ResponseTimeout

Hyperlink Flow

Request

Response

Hyperlink2 URI

Client

Server

ResponseTimeoutRequest

ResponseHyperlink1 URIHyperlink2 URI

Client

Server

RequestHyperlink1 URI

Client

Server

AlternativeResponse

Client

Server

AlternativeResponse

Client

Server

RequestHyperlink2 URI

Response

RESTalk

Standard BPMN Choreography



RESTalk vs. Standard BPMN Choreography -‐41% of respondents-‐

31



RESTalk vs. Standard BPMN Choreography -‐41% of respondents-‐

80%$

60%$

75%$

20%$

40%$

13%$

0%$ 0%$

13%$

0%$

10%$

20%$

30%$

40%$

50%$

60%$

70%$

80%$

90%$

Concise$ Expressive$$ Understandable$

More$

Equally$

Less$

Reading task -‐Long Running Request-‐

32

POST /job



200 OK

DELETE /job/42

200 OKGET /job/42


GET /job/42/output

200 OK



Reading task -‐Long Running Request-‐

33

POST /job



200 OK

DELETE /job/42

200 OKGET /job/42


GET /job/42/output

200 OK

11%#

56%#

62%#

72%#

72%#

77%#

81%#

83%#

85%#

66%#

0%# 10%# 20%# 30%# 40%# 50%# 60%# 70%# 80%# 90%#

How#many#resources#are#created#during#this#conversa?on#

The#client#must#delete#the#job#output#resource#aEer#it#reads#it#

You#can#access#the#job#output#without#having#a#link#to#the#job#itself#

What#happens#when#you#try#to#access#the#job#resource#while#the#job#has#not#completed#yet#

The#job#resource#can#be#deleted#without#dele?ng#the#job#output#resource#

The#job#output#resource#gets#automa?cally#deleted#once#the#client#has#read#it#

The#client#can#decide#to#delete#the#job#output#resource#only#aEer#it#has#read#it#

When#can#you#delete#the#job#resource#

The#client#can#read#the#job#output#mul?ple#?mes#

Average#

Correct answers by sector: 86% in academia and 68% in industry



73%

34

Modeling task -‐CRUD opera6ons on a resource-‐



35

Would use RESTalk – 78% Would prefer a tool – 69%

RESTalk’s evalua6on Mo6va6on è RESTalk è RESTalk Exploratory Survey è Conclusions


83%$77%$

93%$

0%$

10%$

20%$

30%$

40%$

50%$

60%$

70%$

80%$

90%$

100%$

Easily$understandable$ Time$efficient$ Concise$

Posi%ve(Sen%ment(

Conclusions

36

Take-‐Aways Further exis6ng work Future work

37

•  Goal 1: Evaluate the need in industry for a domain specific language for modeling RESTful conversa6ons

Explora6ve Survey Goals

*Qualita=ve research technique => No sta=s=cal inference



•  Goal 2: Evaluate the cogni6ve characteris6cs of RESTalk

38

38% already using some nota6on 78% willing to use RESTalk


Take Aways è Further Exis6ng Work è Future Work

Take away -‐Goal 1: Evaluate the need in industry for a DSML-‐

Intui4veness: 77% correct answers without prior RESTalk knowledge Feedback: include the ra6onale behind server’s decisions at XOR gateways

Closeness of mapping to the problem world: 61% found RESTalk more concise than what they are using Feedback: make state transi6ons and looping limits explicit in RESTalk

Abstrac4on gradient: 83% found RESTalk easy or somewhat easy to understand Feedback: use end events only amer a DELETE method and make dependencies among resources explicit

39

Take away -‐Goal 2: Evaluate the cogni6ve characteris6cs of RESTalk-‐



RESTalk Extension -‐  roles -‐  state transi6ons -‐  asynch email interac6ons -‐  mul6party A. Ivanchikj. RESTful Conversa>on with RESTalk –The Use Case of Doodle-‐. In Proc. of ICWE. Springer, 2016

40

Request

ResponseHyperlink URI

State VariableClient-Server

Interaction With Resource State Change

To: Link: Hyperlink URI

Sending Email Activity

III Multiple ClientsParticipantRoles

Further Exis6ng Work Mo6va6on è RESTalk è RESTalk Exploratory Survey è Conclusions

Take Aways è Further Exis=ng Work è Future Work

RESTalk Paeern Language hep://restalk-‐paeerns.org

C. Pautasso, A. Ivanchikj, and S. Schreier. A PaMern Language for RESTful Conversa>ons. In Proc. Of EuroPLoP. ACM, 2016.

Future Work

41

RESTalk Use

Survey Experiment

Feedback implementa6on

With sta6s6cal relevance

Applied: -‐  on paeerns -‐  on real APIs -‐  by prac66oners

Tool development: -‐ natural language -‐ graphical modeling -‐ code genera6on



Contact us at: [email protected]

[email protected] [email protected]

Contribute to our research on RESTful conversa6on paeerns! hep://restalk-‐paeerns.org/contribute.html

models'16 - restalk

Software