REST APIs are nowadays the de-facto standard for Web applications. However, as more systems and services adopt the REST architectural style, many problems arise regularly. To avoid these repetitive problems, developers should follow good practices and avoid bad practices. Thus, research on good and bad practices and how to design a simple but effective REST API are essential. Yet, to the best of our knowledge, there are only a few concrete solutions to recurring REST API practices, like “API Versioning”. There are works on defining or detecting some practices, but not on solutions to the practices. We present the most up-to-date list of REST API practices and formalize them in the form of REST API (anti)patterns. We validate our design (anti)patterns with a survey and interviews of 55 developers.

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