Are REST APIs Well Designed? Detecting Linguistic Patterns and Antipatterns

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

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

RESTful APIs
GET PUT POST DELETE
HTTP
Method
Resource
Location
of 28

RESTful APIs
GET PUT POST DELETE
HTTP
Method
Resource
Location
Resource
Representation
of 28

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

Use of Underscore
or Capital
Resource Identifier:
Hinder
Interoperability

Use of Underscore
or Capital
Resource Identifier:
Hinder
Interoperability
No hierarchical relations
among resources: Hinder
understandability

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

GET
https://api.instagram.com/v1/media/951585698083207827_477821501/likes?access_token=...
GET
https://api.instagram.com/v1/users/self/followed-by?access_token=482615388.1fb23...
• Two HTTP GET requests for Instagram

GET
https://api.instagram.com/v1/media/951585698083207827_477821501/likes?access_token=...
Contextless Resource
Names
GET
https://api.instagram.com/v1/users/self/followed-by?access_token=482615388.1fb23...
Contextualised Resource
Names
• Two HTTP GET requests for Instagram

POST
https://api.dropbox.com/1/fileops/create_folder?
root=dropbox&path=MyDropboxFolder/20150401/PicsOnly
POST
https://api.dropbox.com/1/fileops/delete?
root=dropbox&path=MyDropboxFolder/MyDropboxFolderApril2014/MyDropboxNewFolderPic
s
• Two HTTP POST requests for Dropbox

POST
https://api.dropbox.com/1/fileops/create_folder?
root=dropbox&path=MyDropboxFolder/20150401/PicsOnly
Amorphous URIs
POST
https://api.dropbox.com/1/fileops/delete?
root=dropbox&path=MyDropboxFolder/MyDropboxFolderApril2014/MyDropboxNewFolderPic
s
Tidy URIs
• Two HTTP POST requests for Dropbox

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

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

Related Work: Software Code Lexicons
8 of 28

Related Work: Lexical/Semantic Analysis
9 of 28

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

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)pattern
s
REST APIs
Implementation
of Interfaces
Implementation
of Algorithms
Services
Interfaces
Methods
Invocation
Application
Request
URIs
Step 1
Analysis
Step 2
Implementation
Step 3
Detection

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

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: 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

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

Approach (5 of 5): Framework
Service
Oriented
Framework for
Antipatterns
• REST Handler
- Provides a wrapper layer
- Automatically applies detection algorithms on REST URIs

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…

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

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

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

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

Results (1 of 7): Detection Summary

Results (3 of 7): Detection
22Are RESTful APIs Well-designed? of 28

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%

23

DOALR has a high accuracy in terms of
precision and recall
(Anti)Patterns
Validation 1
(Dropbox)
Validation 2
(On Subset)
Precision Recall Precision
100% 100% 53.3%
60.7% 66.7% 58.3%
Tidy URIs
96.2% 87.5% 100%
Verbless URIs
vs. CRUDy URIs
90% 87.5% 100%
60% 48.3% 86.7%
Average 81.4% 78% 79.7%
Are RESTful APIs Well-designed? of 28

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

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

The implemented algorithms perform with
considerably a low detection times
25
(Anti)Patterns
Average
Detection
Time
vs. Contextless Resource Names 0.613s
vs. Non-hierarchical Nodes 0.589s
Tidy URIs
vs. Amorphous URIs 0.976s
Verbless URIs
vs. CRUDy URIs 0.707s
vs. Pluralised Nodes 0.662s
Average 0.709s

25
The implemented algorithms perform with
considerably a low detection times

(Anti)Patterns
Average
Detection
Time
0.613s
0.589s
Tidy URIs
0.976s
Verbless URIs
vs. CRUDy URIs
0.707s
0.662s
Average 0.709s

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/

Conclusion

Future Work
• Apply DOLAR on other RESTful APIs
• Perform validation of DOLAR results with APIs developers
• Analyse HTTP responses for linguistic (anti)patterns

Are REST APIs Well Designed? Detecting Linguistic Patterns and Antipatterns

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (11)

En vedette

En vedette (7)

Similaire à Are REST APIs Well Designed? Detecting Linguistic Patterns and Antipatterns

Similaire à Are REST APIs Well Designed? Detecting Linguistic Patterns and Antipatterns (20)

Plus de Francis Palma

Plus de Francis Palma (14)

Dernier

Dernier (20)

Are REST APIs Well Designed? Detecting Linguistic Patterns and Antipatterns