UNIVERSITY OF CALGARY Automated Example Oriented REST …
UNIVERSITY OF CALGARY
Automated Example Oriented REST API Documentation
by
S M Sohan
A THESIS SUBMITTED TO THE FACULTY OF GRADUATE STUDIES IN PARTIAL FULFILLMENT OF THE REQUIREMENTS FOR THE
DEGREE OF DOCTOR OF PHILOSOPHY
GRADUATE PROGRAM IN COMPUTER SCIENCE
CALGARY, ALBERTA September, 2017
? S M Sohan 2017
UNIVERSITY OF CALGARY FACULTY OF GRADUATE STUDIES
The undersigned certify that they have read, and recommend to the Faculty of Graduate Studies for acceptance, a thesis entitled "Automated Example Oriented REST API Documenation" submitted by S M Sohan in partial fulfillment of the requirements for the degree of DOCTOR OF PHILOSOPHY.
Dr. Frank Maurer Supervisor
Department of Computer Science University of Calgary, Canada
Dr. Mea Wang Supervisory Committee Member Department of Computer Science
University of Calgary, Canada
Dr. Craig Anslow Supervisory Committee Member
School of Engineering and Computer Science
Victoria University of Wellington, New Zealand
Dr. Nils Daniel Forkert Internal Examiner
Department of Radiology and Hotchkiss Brain Institute
University of Calgary, Canada
Dr. Yves Lucet External Examiner Computer Science University of British Columbia (Okanagan), Canada
Date
iii
Abstract
API documentation presents both a problem and an opportunity for API usability. REST APIs provide interconnectivity between applications over HTTP. Documentation of a REST API is a key information source for API client developers. Most REST APIs are documented using a manual approach, which can be time consuming and error-prone. REST API developers need to efficiently document their APIs with qualities that make the API usable. In this research, I focused on the topic of automated REST API documentation to satisfy this need.
In this thesis, I present and evaluate of a novel technique to solve REST API documentation requirements. I present a set of REST API documentation requirements by studying the existing literature and the current industry practice. From this study, I observed that REST APIs evolve frequently, but used a manual or bespoke approach for generating and maintaining their documentation. I present, SpyREST, a reusable technique with a prototype implementation to automate the REST API documentation process with executable API usage examples. The technique involves the interception of example REST API calls using an HTTP proxy server to auto-generate an accurate and updated REST API documentation. I present an industrial evaluation of the proposed technique based on a period of eighteen months of production use. From this study, I found that it was feasible to leverage API test code to automatically generate an always-updated REST API documentation for evolving REST APIs with usage examples. To evaluate the impact of usage examples on REST API client developers, I performed a controlled study with experienced REST API developers. From this case study, I found that REST API client developers faced patterns of obstacles using REST APIs that can be reduced by including API usage examples in the API documentation, as suggested in the proposed technique.
The findings of this research can be used as a guideline by practitioners to automatically generate REST API documentation with usage examples. Researchers can extend the novel concept of using interception to automatically document API usage examples for other forms of APIs.
iv
Acknowledgements
I am grateful to Shahana, my wife, for supporting me and the family while I took an unacceptable amount of the time and attention away from them to work on this research.
I am thankful to my supervisor Dr. Frank Maurer for giving me the opportunity and valuable guidance to pursue this research. I am also thankful to Dr. Craig Anslow for his continuous encouragement and the countless number of hours that he spent to provide feedback about my work.
I am grateful to Cisco for allowing me to pursue this research alongside my job. I am grateful to the study participants in my case studies for sharing their time with me on the experiments.
v
Dedication
To my dear wife.
vi
Contents
Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iv Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v Dedication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi List of Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 Research Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 Research Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3 Cohesion and Unitary Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.4 Contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.5 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2 A Case Study of Web API Evolution . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 2.3 Related Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.3.1 Empirical Research on Web API Evolution . . . . . . . . . . . . . . . . . 14 2.3.2 Techniques to Evolve Web APIs . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.3 Tool Support for Evolving Web APIs . . . . . . . . . . . . . . . . . . . . 17 2.4 Case Study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.4.1 Research Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.4.2 Selection Strategy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.4.3 Research Method - Qualitative Analysis . . . . . . . . . . . . . . . . . . . 18 2.5 Findings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.5.1 RQ1 Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.5.2 RQ2 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 2.5.3 RQ3 Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 2.6 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 2.7 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 2.8 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3 SpyREST: Automated RESTful API Documentation using an HTTP Proxy Server . 38 3.1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 3.3 Related Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 3.3.1 General API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . 40 3.3.2 RESTful API Documentation . . . . . . . . . . . . . . . . . . . . . . . . 41 3.4 SpyREST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 3.4.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 3.4.2 Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 3.4.3 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3.5 SpyREST Case Study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
vii
3.5.1 SpyREST Documentation vs. Official Documentation . . . . . . . . . . . 48 3.6 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.6.1 Threats to Validity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 3.7 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 3.8 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 4 SpyREST in Action: An Automated RESTful API Documentation Tool . . . . . . 55 4.1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 4.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 4.3 SpyREST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.3.1 Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 4.3.2 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 4.4 Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 4.4.1 Initial API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 60 4.4.2 Maintaining API Documentation for Evolving APIs . . . . . . . . . . . . . 62 4.5 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 4.6 Related Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 4.7 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 4.8 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 5 Automated Example Oriented REST API Documentation at Cisco . . . . . . . . . 71 5.1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 5.2 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 5.3 Related Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 5.3.1 API Usability and Documentation . . . . . . . . . . . . . . . . . . . . . . 73 5.3.2 Usage Examples in API Documentation . . . . . . . . . . . . . . . . . . . 74 5.3.3 REST API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . 75 5.4 REST API Documentation Tool Selection . . . . . . . . . . . . . . . . . . . . . . 77 5.4.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 5.4.2 Evaluation of Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 5.5 SpyREST ? Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 5.6 Case Study: SpyREST at Cisco . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 5.6.1 Methodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 5.6.2 Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 5.6.3 The API Development Process . . . . . . . . . . . . . . . . . . . . . . . . 86 5.7 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 5.7.1 REST API Documentation from Test Code . . . . . . . . . . . . . . . . . 90 5.7.2 Maintaining Custom Content . . . . . . . . . . . . . . . . . . . . . . . . . 91 5.7.3 Handling Flexible API Elements . . . . . . . . . . . . . . . . . . . . . . . 92 5.7.4 API Documentation Life-cycle . . . . . . . . . . . . . . . . . . . . . . . . 93 5.7.5 API Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 5.7.6 Cross-Referencing API Elements . . . . . . . . . . . . . . . . . . . . . . 94 5.7.7 Extending beyond REST API Documentation . . . . . . . . . . . . . . . . 95 5.7.8 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 5.8 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 5.9 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 6 A Study of the Effectiveness of Usage Examples in REST API Documentation . . 101
viii
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related download
- restler stateful rest api fuzzing github pages
- rit rest api tutorial
- rest api reference guide oracle
- interaction designer rest api tools developer s guide
- rest api guide supportassist enterprise
- general api developer guide usps
- documentation rvtools
- university of calgary automated example oriented rest
- a study of the effectiveness of usage examples in rest api
Related searches
- university of minnesota college of education
- university of minnesota school of social work
- wharton school of the university of pennsylvania
- cost of university of scranton
- university of minnesota school of education
- university of scranton cost of attendance
- university of south florida college of medicine
- university of minnesota masters of social work
- ecampus of university of phoenix
- university of minnesota college of continuing education
- university of illinois college of nursing
- university of north texas college of nursing