1.
Formalising Solutions to REST API Practices
as Design (Anti)patterns
Van Tuan Tran, Manel Abdellatif and Yann-Gaël Guéhéneuc
Presenting at The 19th International Conference on Service-Oriented Computing

2.
Table of Contents
1. Introduction
2. Related Work
3. Approach
4. (Anti)patterns
5. Evaluations
6. Discussion
7. Conclusion
2

3.
1 - Introduction
3

4.
1 - Introduction - Context
4
https://github.com/features/codespaces - https://www.windy.com/

5.
1 - Introduction - Context
5

6.
1 - Introduction - Context
6
REpresentational State Transfer
Application Programming Interface

7.
1 - Introduction - Context
7
REpresentational State Transfer
Application Programming Interface

8.
1 - Introduction - Terms
8
Practice noun
/ˈpræktɪs/
way of doing something
Good practice
good way to implement the REST API
Bad practice
Bad way to implement the REST API
https://www.oxfordlearnersdictionaries.com/us/definition/english/practice_1

9.
1 - Introduction - Terms
9
Anti-pattern
“A commonly occurring solution to a problem that generates
negative consequences”
Problem Bad solution(s) Alternative good solution(s)

10.
1 - Introduction
10
We propose 3 contributions
● Review academic and gray literature to identify REST API practices
● Propose practical solutions to these practices
● Validate our solutions with surveys and interviews

11.
2 - Related Work
11

12.
2 - Related Work - Practices
12
2010 - Content Negotiations
2011 - CRUDYs URIs
Use the wrong HTTP Verbs
Ignoring MIME Type
Context-less resource name
Non-hierarchical nodes
Singularized/Pluralized Nodes
List Pagination
2012 - API Versioning
Masse
2008 - Breaking Self-descriptiveness
Forgetting Hypermedia
Ignoring MIME type
Ignoring status code
Misusing cookies
Use the wrong HTTP Verbs
Stefan Tilkov
Rodriguez,
Crasso,
Zunino, and
Campo
Fredrich

13.
2 - Related Work - Practices
13
2010 - Content Negotiations
2011 - CRUDYs URIs
Use the wrong HTTP Verbs
Ignoring MIME Type
Context-less resource name
Non-hierarchical nodes
Singularized/Pluralized Nodes
List Pagination
2012 - API Versioning
2008 - Breaking Self-descriptiveness
Forgetting Hypermedia
Ignoring MIME type
Ignoring status code
Misusing cookies
Use the wrong HTTP Verbs
Non-pertinent documentation - 2017
Palma et al.

14.
2 - Related Work - Practices
14
2010 - Content Negotiations
2011 - CRUDYs URIs
Use the wrong HTTP Verbs
Ignoring MIME Type
Context-less resource name
Non-hierarchical nodes
Singularized/Pluralized Nodes
List Pagination
2012 - API Versioning
2008 - Breaking Self-descriptiveness
Forgetting Hypermedia
Ignoring MIME type
Ignoring status code
Misusing cookies
Use the wrong HTTP Verbs
Non-pertinent documentation - 2017
Server Timeout - 2021
Post-Put-Patch return - 2021

15.
2 - Related Work - Existing Solutions
15
● Content Negotiation
● Forgetting Hypermedia
● API Versioning
● Server Timeout
● Response Caching
● List Pagination

16.
2 - Related Work - Existing Solutions
16
● Content Negotiation
● Forgetting Hypermedia
● API Versioning
● Server Timeout
● Response Caching
● List Pagination
XML
JSON
Lemlouma
and Layaïda

17.
2 - Related Work - Existing Solutions
17
● Content Negotiation
● Forgetting Hypermedia
● API Versioning
● Server Timeout
● Response Caching
● List Pagination
XML
JSON
Butler

18.
2 - Related Work - Existing Solutions
18
● Content Negotiation
● Forgetting Hypermedia
● API Versioning
● Server Timeout
● Response Caching
● List Pagination
wrapper
Liskin, Singer,
and Schneider

19.
2 - Related Work - Existing Solutions
19
● Content Negotiation
● Forgetting Hypermedia
● API Versioning
● Server Timeout
● Response Caching
● List Pagination
Chain of Adapter
Kaminski, Litoiu,
and Muller

20.
2 - Related Work - Existing Solutions
20
● Content Negotiation
● Forgetting Hypermedia
● API Versioning
● Server Timeout
● Response Caching
● List Pagination
Version 1
Version 2
Version 1
Version 2
Leitner, Michlmayr,
Rosenberg, and
Dustdar

21.
2 - Related Work - Existing Solutions
21
● Content Negotiation
● Forgetting Hypermedia
● API Versioning
● Server Timeout
● Response Caching
● List Pagination
Eastbury et al.

22.
2 - Related Work - Existing Solutions
22
● Content Negotiation
● Forgetting Hypermedia
● API Versioning
● Server Timeout
● Response Caching
● List Pagination
https://github.com/campusMVP/dotnetCoreLogoPack - https://spring.io/trademarks

23.
3 - Approach
23

24.
24
2 - Approach - Literature Review

25.
25
2 - Approach - Categorization
Technical Non-technical
Content negotiation Entity Endpoint
Endpoint redirection Contextless Resource name
Entity Linking Non-hierarchical Nodes
Response caching Amorphous URIs
API Versioning CRUDy URIs
Server Timeout Singularized & Pluralized Nodes
POST-PUT-PATCH Return Non-pertinent Documentation
List Pagination Breaking Self-descriptiveness
Ignoring status code
Using the wrong HTTP Verbs
Misusing Cookies
Architectural
Devs pay attention

26.
26
2 - Approach - Looking for Solutions

27.
4 - REST API Anti-patterns
27

28.
4 - REST API Anti-patterns - Overview
28
● Practice name
● Problem
● Expected result
● Solution

29.
4 - REST API Anti-patterns - Sample Implementation
29
https://github.com/huntertran/restapi-practices-impl

30.
4 - REST API Anti-patterns - Content Negotiation
30
● Problem
XML
JSON

31.
2 3
1
4 - REST API Anti-patterns - Content Negotiation
31
● Expected result
XML
JSON
default
● JSON-XML
● JPG, PNG, Base64
● CSV, XLSX, ODS
● JSON-XML
● JPG, PNG, Base64
● CSV, XLSX, ODS
Easily modifiable
● GSON/Jackson/Javax.Json
● Javax.ImageIO/ImageJ/imgscalr
● FileReader/XStream/JacksonXML

32.
4 - REST API Anti-patterns - Content Negotiation
32
● Solution

33.
4 - REST API Anti-patterns - Content Negotiation
33
● Comparison
Java Spring ASP.NET Core Our solution
Common media types Yes Yes Yes
Customizable serializer No Yes Yes
No data annotation on model No Yes Yes
Built-in support ignorable Yes Yes N/A

34.
4 - REST API Anti-patterns - Endpoint Redirection
34
● Problem
New location of
moved resources
O
l
d
U
R
I
H
T
T
P
3
0
2
M
o
v
e
d

35.
4 - REST API Anti-patterns - Endpoint Redirection
35
● Solution

36.
4 - REST API Anti-patterns - Entity Linking
36
● Problem
{
"post": {
"title": "Lorem ipsum",
"content": "Lorem ipsum",
"links": [
{
"rel": "comment",
"method": "post",
"uri": "/post/123/comment"
},
{
"rel": "like",
"method": "get",
"uri": "/post/123/like"
}
]
}
}

37.
4 - REST API Anti-patterns - Entity Linking
37
● Solution

38.
4 - REST API Anti-patterns - API Versioning
38
● Problem
Version 1
Version 2
Version 1
Version 2

39.
4 - REST API Anti-patterns - API Versioning
39
● Solution

40.
4 - REST API Anti-patterns - Server Timeout
40
● Problem

41.
4 - REST API Anti-patterns - Server Timeout
41
● Solution

42.
4 - REST API Anti-patterns - POST-PUT-PATCH return
42
● Problem
CREATE - UPDATE
HTTP 200 OK
Is object created correctly?

43.
4 - REST API Anti-patterns - POST-PUT-PATCH return
43
● Solution

44.
5 - Evaluations
44

45.
5 - Evaluations - Survey Design
45
● Have you faced this problem(s)
in some of your project
● Is the proposed solution a good
solution?
https://acmsigsoft.github.io/EmpiricalStandards/docs/
55 participants 5 participants

46.
5 - Evaluations - Survey Result - Age Groups & Education
46
Age Groups Education Levels

47.
5 - Evaluations - Survey Result - Profession
47

48.
5 - Evaluations - Survey Result - Experience
48

49.
5 - Evaluations - Survey Result - Countries
49

50.
5 - Evaluations - Survey Result - Positive on Solutions
50
Face this problem Std. dev. Good solution Std. dev.
Content Negotiation 52.40% 2.289 76.20% 1.952
Endpoint Redirection 45% 2.225 75% 1.936
Entity Linking 47.40% 2.177 57.90% 2.152
API Versioning 72.20% 1.901 72.20% 1.901
Server Timeout 77.80% 1.763 66.70% 1.999
POST-PUT-PATCH return 58.80% 2.029 82.40% 1.57
70%

51.
5 - Evaluations - Survey Result - Explained
51
Entity Linking - 57.9% agreed good solution
Visitor Pattern

52.
Visitor Pattern
5 - Evaluations - Survey Result - Explained
52
Entity Linking - 57.9% agreed good solution
List of permissions

53.
5 - Evaluations - Survey Result - Explained
53
Server Timeout - 66.7% agreed good solution
HTTP Polling
Publisher
HTTP/2 gRPC

54.
5 - Evaluations - Survey Result - Explained
54
Server Timeout - 66.7% agreed good solution
WebSocket Tunnel
HTTP Polling

55.
5 - Evaluations - Survey Result - Explained
55
Server Timeout - 66.7% agreed good solution
Publisher

56.
5 - Evaluations - Survey Result - Explained
https://engineering.salesforce.com/the-full-picture-on-http-2-and-hol-blocking-7f964b34d205 56
Server Timeout - 66.7% agreed good solution
HTTP/2 gRPC
Forced Encryption TPC Head-of-line Blocking

57.
6 - Discussion
57

58.
6 - Discussion - Internal Threats
58
JavaScript Go Groovy Java
Gin
Grails Apache Struts

59.
6 - Discussion - External Threats
59
Year of experiences
Domain Knowledge
Favor new technologies
Easier to spot potential
problems of the practices

60.
7 - Conclusion
60

61.
7 - Conclusion
61
Our contributions:
1. Review REST API practices in both academic and gray literature.
2. Provide concrete solutions to 6 technical practices.
3. Validate the solutions with professional developers.

62.
Thank you
Q & A
62