Are RESTful APIs Well-designed? Detection of their Linguistic (Anti)Patterns?

1. Are RESTful APIs Well-designed?
Detection of their Linguistic (Anti)Patterns
Francis Palma, Javier Gonzalez-Huerta, Naouel Moha,
Yann-Gaël Guéhéneuc, and Guy Tremblay
ICSOC 2015, Goa, India

2. RESTful APIs
GET PUT POST DELETE
Are RESTful APIs Well-designed? 2
HTTP
Method
of 28

3. RESTful APIs
GET PUT POST DELETE
Are RESTful APIs Well-designed? 2
HTTP
Method
Resource
Location
of 28

4. RESTful APIs
GET PUT POST DELETE
Are RESTful APIs Well-designed? 2
HTTP
Method
Resource
Location
Resource
Representation
of 28

5. Problem Context (1 of 3)
Unpredictable Context
Are RESTful APIs Well-designed? 3 of 28

6. Problem Context (1 of 3)
Unpredictable Context
Use of Underscore
or Capital Resource
Identifier: Hinder
Interoperability
Are RESTful APIs Well-designed? 3 of 28

7. Problem Context (1 of 3)
Unpredictable Context
Use of Underscore
or Capital Resource
Identifier: Hinder
Interoperability
No hierarchical relations
among resources: Hinder
understandability
Are RESTful APIs Well-designed? 3 of 28

8. Linguistic Patterns and Antipatterns
• Linguistic antipatterns are poor solutions to common recurring
naming problems, which may hinder:
• the consumption and
• the maintenance of RESTful APIs
• Linguistic patterns are best solutions to common naming problems
Are RESTful APIs Well-designed? 4 of 28

9. GET
https://api.instagram.com/v1/media/951585698083207827_477821501/likes?access_token=...
Problem Context (2 of 3)
GET
https://api.instagram.com/v1/users/self/followed-by?access_token=482615388.1fb23...
• Two HTTP GET requests for Instagram
Are RESTful APIs Well-designed? 5 of 28

10. GET
https://api.instagram.com/v1/media/951585698083207827_477821501/likes?access_token=...
Problem Context (2 of 3)
GET
https://api.instagram.com/v1/users/self/followed-by?access_token=482615388.1fb23...
• Two HTTP GET requests for Instagram
Are RESTful APIs Well-designed? 5 of 28

11. POST
https://api.dropbox.com/1/fileops/create_folder?root=dropbox&path=MyDropboxFolder/201504
01/PicsOnly
Problem Context (3 of 3)
POST
https://api.dropbox.com/1/fileops/delete?root=dropbox&path=MyDropboxFolder/MyDropboxF
olderApril2014/MyDropboxNewFolderPics
• Two HTTP POST requests for Dropbox
Are RESTful APIs Well-designed? 6 of 28

12. POST
https://api.dropbox.com/1/fileops/create_folder?root=dropbox&path=MyDropboxFolder/201504
01/PicsOnly
Problem Context (3 of 3)
POST
https://api.dropbox.com/1/fileops/delete?root=dropbox&path=MyDropboxFolder/MyDropboxF
olderApril2014/MyDropboxNewFolderPics
• Two HTTP POST requests for Dropbox
Are RESTful APIs Well-designed? 6 of 28

13. Outline
- Contribution on the detection of REST linguistic (anti)patterns
- State of the art contributions
- Our proposed DOLAR approach
- Experiments and some initial results

14. Outline
- Contribution on the detection of REST linguistic (anti)patterns
- State of the art contributions
- Our proposed DOLAR approach
- Experiments and some initial results

15. Contributions
Goal: To assess the URIs design in RESTful APIs
• DOLAR (Detection Of Linguistic Antipatterns in REST)
- a heuristics-based approach
• SOFA (Service Oriented Framework for Antipatterns), an underlying
framework to support the detection of SOA antipatterns
• Empirical evidence of the presence of REST linguistic (anti)patterns
Are RESTful APIs Well-designed? 7 of 28

16. Outline
- Contribution on the detection of REST linguistic (anti)patterns
- State of the art contributions
- Our proposed DOLAR approach
- Experiments and some initial results

17. Related Work: Software Code Lexicons
8 of 28

18. Related Work: Software Code Lexicons
8 of 28

19. Related Work: Lexical/Semantic Analysis
9 of 28

20. Related Work: Lexical/Semantic Analysis
9 of 28

21. Related Work: Lexical/Semantic Analysis
9 of 28

22. Related Work: Lexical/Semantic Analysis
9 of 28

23. Related Work: Lexical/Semantic Analysis
9 of 28

24. Related Work: Lexical/Semantic Analysis
9 of 28

25. Related Work: Summary
- Existing approaches deal with
• Object-oriented identifiers and their consistencies with
comments
• Traditional SOAP-based Web services interfaces
- Analyses of RESTful APIs
• Based on subjective lexical comparisons
• Do not provide an automatic analysis
 No dedicated approach to automatically assess the linguistic
quality
of RESTful APIs
Are RESTful APIs Well-designed? 10 of 28

26. Outline
- Contribution on the detection of REST linguistic (anti)patterns
- State of the art contributions
- Our proposed DOLAR approach
- Experiments and some initial results

27. Approach (1 of 5): DOLAR
DOLAR: Detection Of Linguistic Antipatterns in REST
Analysis
Description of
REST linguistic
(anti)patterns
Heuristics
Detection
Algorithms
Detected
Linguistic
(anti)patterns
REST APIs
Implementation
of Interfaces
Implementation
of Algorithms
Services
Interfaces
Methods
Invocation
Application
Request
URIs
Step 1
Analysis
Step 2
Implementation
Step 3
Detection
Are RESTful APIs Well-designed? 11 of 28

28. Approach (2 of 5): Analysis
• Identify syntactic aspects:
o For example: Amorphous/Tidy URIs
• Identify semantic aspects:
o For example: Contextless/Contextualised Resource Names
• Analyse relationships among URI nodes. For example:
hypernym-hyponym relation meronym-holonym relation
Are RESTful APIs Well-designed? 12 of 28

29. 1: Contextless-Resource-Names(Request-URI)
2: URINodes ← Extract-URI-Nodes(Request-URI)
3: for each index = 1 to Length(URINodes)-1
4: Set1 ← Capture-Context-by-Synsets(URINodesindex)
5: Set2 ← Capture-Context-by-Synsets(URINodesindex+1)
6: if Set1 ∩ Set2 = ∅
7: print “Contextless Resource Names detected”
8: break
9: end if
10: end for
Heuristic of Contextless Resource Names antipattern
Approach (3 of 5): Heuristics
Are RESTful APIs Well-designed? 13 of 28

30. 1: Contextless-Resource-Names(Request-URI)
2: URINodes ← Extract-URI-Nodes(Request-URI)
3: for each index = 1 to Length(URINodes)-1
4: Set1 ← Capture-Context-by-Synsets(URINodesindex)
5: Set2 ← Capture-Context-by-Synsets(URINodesindex+1)
6: if Set1 ∩ Set2 = ∅
7: print “Contextless Resource Names detected”
8: break
9: end if
10: end for
Heuristic of Contextless Resource Names antipattern
Approach (3 of 5): Heuristics
1: Amorphous-URI(Request-URI)
2: URINodes[] ← Extract-URI-Nodes(Request-URI)
3: for each index = 1 to Length(URINodes)
4: if(URINodesi.contains(“_”) or
5: URINodesi.contains(“/”) or
6: URINodesi.contains(Find-File-Extensions(Request-URI)) or
7: URINodesi.contains(Find-Uppercase-Resources(Request-URI)))
8: print “Amorphous URI detected”
9: end if
10: end for
Heuristic of Amorphous URIs antipattern
Are RESTful APIs Well-designed? 13 of 28

31. Approach (4 of 5): Detection
Detection
Algorithms
Service
Interfaces
Dynamic
Invocation
Parameterised
HTTP Requests
and Responses
Implemented
Client
Client
Authentication
Detected
REST Linguistic
(anti)patterns
Application
Are RESTful APIs Well-designed? 14 of 28

32. Approach (5 of 5): Framework
Service
Oriented
Framework for
Antipatterns
• REST Handler
- Provides a wrapper layer
- Automatically applies detection algorithms on REST URIs
Are RESTful APIs Well-designed? 15 of 28

33. Outline
- Contribution on the detection of REST linguistic (anti)patterns
- State of the art contributions
- Our proposed DOLAR approach
- Experiments and some initial results

34. Experiments (1 of 5): Setup
 Purpose is to show
- the accuracy of DOLAR approach
- the extensibility of our SOFA framework, and
- low performance overhead of the detection algorithms
 Subjects
- 5 REST linguistic antipatterns
- 5 REST linguistic patterns
 Objects
and 10 more…
Are RESTful APIs Well-designed? 16 of 28

35. Experiments (2 of 5): Hypotheses
H1. Accuracy
The set of all defined rules have an average precision and recall of more than 75%,
i.e., more than three out of four are true positives and we do not miss more than one
out of four of all existing (anti)patterns
H2. Extensibility
Our SOFA framework is extensible for adding new service-oriented and REST-specific
(anti)patterns. In addition, SOFA facilitates an easy integration of new RESTful APIs
H3. Performance
The concretely implemented detection algorithms perform with a low detection times,
i.e., on an average in the order of seconds
Are RESTful APIs Well-designed? 17 of 28

36. Experiments (3 of 5): Subjects
10 REST linguistic (anti)patterns
• Contextualised Resource Names vs. Contextless Resource Names
• Hierarchical Nodes vs. Non-hierarchical Nodes
• Tidy URIs vs. Amorphous URIs
• Verbless URIs vs. CRUDy URIs
• Singularised Nodes vs. Pluralised Nodes
Are RESTful APIs Well-designed? 18 of 28

37. Experiments (4 of 5): Objects
REST APIs Online Documentations
alchemyapi.com/api/
bbyopen.com/developer/
dev.bitly.com/api.html
charlieharvey.org.uk/about/api/
dropbox.com/developers/core/docs/
developers.facebook.com/docs/graph-api/
developer.musicgraph.com/api-docs/overview/
github.com/blackducksw/ohloh_api/
integrate.teamviewer.com/en/develop/documentation/
dev.twitter.com/docs/api/
developers.google.com/youtube/v3/
developer.zappos.com/docs/api-documentation/
api.externalip.net
instagram.com/developer
api.stackexchange.com.docs
Are RESTful APIs Well-designed? 19 of 28

38. Experiments (5 of 5): Process
• Define heuristics for 10 REST linguistic (anti)patterns
• Implement clients and invoke 309 methods from APIs
• Apply detection algorithms on parameterised HTTP requests URIs
• Manually validate detection results to identify true positives and false
negatives (on a subset of methods)
• Use precision and recall to measure detection accuracy
Are RESTful APIs Well-designed? 20 of 28

39. Results (1 of 7): Detection Summary
Are RESTful APIs Well-designed? 21 of 28

40. Results (3 of 7): Detection
(9)Alchemy
(20)BestBuy
(15)Bitly
(12)CharlieHarvey
(17)DropBox
(6)Externalip
(67)Facebook
(14)Instagram
(19)Musicgraph
(7)Ohloh
(53)StackExchange
(19)TeamViewer
(25)Twitter
(17)YouTube
(9)Zappos
(309)Total
DetectionTime
Contextless
Resource Names
0 0 2 4 1 0 7 4 9 2 6 0 6 1 0
42
(14%)
0.565s
Contextualised
Resource Names
9 0 8 4 14 0 21 8 10 3 28 0 19 6 0
130
(42%)
0.66s
No Detection 0 20 5 4 2 6 39 2 0 2 19 19 0 10 9
137
(44%)
-
22Are RESTful APIs Well-designed? of 28

41. Results (4 of 7): Hypothesis H1
DOALR has a high accuracy in terms of
precision and recall
(Anti)Patterns
Validation 1
(Dropbox)
Validation 2
(On Subset)
Precision Recall Precision
Contextualised Resource Names
vs. Contextless Resource Names
100% 100% 53.3%
Hierarchical Nodes
vs. Non-hierarchical Nodes
60.7% 66.7% 58.3%
Tidy URIs
vs. Amorphous URIs
96.2% 87.5% 100%
Verbless URIs
vs. CRUDy URIs
90% 87.5% 100%
Singularised Nodes
vs. Pluralised Nodes
60% 48.3% 86.7%
Average 81.4% 78% 79.7%
Are RESTful APIs Well-designed? 23 of 28

42. Results (4 of 7): Hypothesis H1
23

DOALR has a high accuracy in terms of
precision and recall
(Anti)Patterns
Validation 1
(Dropbox)
Validation 2
(On Subset)
Precision Recall Precision
Contextualised Resource Names
vs. Contextless Resource Names
100% 100% 53.3%
Hierarchical Nodes
vs. Non-hierarchical Nodes
60.7% 66.7% 58.3%
Tidy URIs
vs. Amorphous URIs
96.2% 87.5% 100%
Verbless URIs
vs. CRUDy URIs
90% 87.5% 100%
Singularised Nodes
vs. Pluralised Nodes
60% 48.3% 86.7%
Average 81.4% 78% 79.7%
Are RESTful APIs Well-designed? of 28

43. Results (5 of 7): Hypothesis H2
The SOFA framework is extensible
• Newly added 10 REST linguistic (anti)patterns
• in total SOFA supports the detection of 23 REST (anti)patterns
• Added 3 new RESTful APIs including
• in total SOFA supports analysis of 15 RESTful APIs
• Tested 190 new REST methods
• Addition of new (anti)patterns and RESTful APIs is flexible
24Are RESTful APIs Well-designed? of 28

44. Results (5 of 7): Hypothesis H2
24

The SOFA framework is extensible
• Newly added 10 REST linguistic (anti)patterns
• in total SOFA supports the detection of 23 REST (anti)patterns
• Added 3 new RESTful APIs including
• in total SOFA supports analysis of 15 RESTful APIs
• Tested 190 new REST methods
• Addition of new (anti)patterns and RESTful APIs is flexible
Are RESTful APIs Well-designed? of 28

45. Results (6 of 7): Hypothesis H3
The implemented algorithms perform with
considerably a low detection times
25
(Anti)Patterns
Average
Detection
Time
Contextualised Resource Names
vs. Contextless Resource Names
0.613s
Hierarchical Nodes
vs. Non-hierarchical Nodes
0.589s
Tidy URIs
vs. Amorphous URIs
0.976s
Verbless URIs
vs. CRUDy URIs
0.707s
Singularised Nodes
vs. Pluralised Nodes
0.662s
Average 0.709s
Are RESTful APIs Well-designed? of 28

46. Results (6 of 7): Hypothesis H3
25
The implemented algorithms perform with
considerably a low detection times

(Anti)Patterns
Average
Detection
Time
Contextualised Resource Names
vs. Contextless Resource Names
0.613s
Hierarchical Nodes
vs. Non-hierarchical Nodes
0.589s
Tidy URIs
vs. Amorphous URIs
0.976s
Verbless URIs
vs. CRUDy URIs
0.707s
Singularised Nodes
vs. Pluralised Nodes
0.662s
Average 0.709s
Are RESTful APIs Well-designed? of 28

47. Results (7 of 7): Validation Summary
• Defined heuristics and implemented detection algorithms for 10
REST linguistic (anti)patterns
• Performed detection on 15 well-known RESTful APIs, including
• Average precision of detection algorithms is between 79.7% and
81.4%, and average recall is 78%
• Detailed results and more materials on sofa.uqam.ca/dolar/
26Are RESTful APIs Well-designed? of 28

48. Conclusion
27Are RESTful APIs Well-designed? of 28

49. Conclusion
27Are RESTful APIs Well-designed? of 28

50. Conclusion
27Are RESTful APIs Well-designed? of 28

51. Conclusion
27Are RESTful APIs Well-designed? of 28

52. Future Work
• Apply DOLAR on other RESTful APIs
• Perform validation of DOLAR results with APIs developers
• Analyse HTTP responses for linguistic (anti)patterns
28Are RESTful APIs Well-designed? of 28

53. Thank you!
Questions?