are restful apis well-designed? detection of their linguistic (anti)patterns

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 APIsGET PUT POST DELETE

Are RESTful APIs Well-designed? 2

HTTP Method

of 28



HTTP Method

Resource Location

of 28



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/MyDropboxNewFolderPics

• 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/MyDropboxNewFolderPicsTidy 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


Outline





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 APIsAre RESTful APIs Well-designed? 10 of 28

Outline





Approach (1 of 5): DOLAR

DOLAR: Detection Of Linguistic Antipatterns in REST

AnalysisDescription of

REST linguistic (anti)patterns

Heu

ristic

s

Det

ectio

nA

lgor

ithm

s

Detected Linguistic

(anti)patterns

REST APIs Implementation of Interfaces

Implementationof Algorithms

Ser

vice

sIn

terfa

ces

MethodsInvocation

Application

Req

uest

UR

Is

Step 1Analysis

Step 2Implementation

Step 3Detection


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)-14: 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: break9: end if10: 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)-14: 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: break9: end if10: 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(“_”) or5: URINodesi.contains(“/”) or6: URINodesi.contains(Find-File-Extensions(Request-URI)) or7: URINodesi.contains(Find-Uppercase-Resources(Request-URI)))8: print “Amorphous URI detected”9: end if10: end for

Heuristic of Amorphous URIs antipattern


Approach (4 of 5): Detection

Detection Algorithms

Service Interfaces

DynamicInvocation

Parameterised HTTP Requests and Responses

ImplementedClient

ClientAuthentication

Detected REST Linguistic

(anti)patternsApplication


Approach (5 of 5): Framework

Service Oriented Framework for Antipatterns

• REST Handler - Provides a wrapper layer - Automatically applies detection algorithms on REST URIs


Outline





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. AccuracyThe 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. ExtensibilityOur 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. PerformanceThe 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)PatternsValidation 1(Dropbox)

Validation 2 (On Subset)

Precision Recall PrecisionContextualised 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)PatternsValidation 1(Dropbox)

Validation 2 (On Subset)

Precision Recall PrecisionContextualised 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


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)PatternsAverage

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



25

The implemented algorithms perform with considerably a low detection times

(Anti)PatternsAverage

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


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


Thank you!Questions?

are restful apis well-designed? detection of their linguistic (anti)patterns

Technology