Automated Example Oriented REST API Documentation

Simple item page
atmire.migration.oldid6178
dc.contributor.advisorMaurer, Frank
dc.contributor.authorSohan, S M
dc.contributor.committeememberAnslow, Craig
dc.contributor.committeememberWang, Mea
dc.date.accessioned2017-11-21T23:03:42Z
dc.date.available2017-11-21T23:03:42Z
dc.date.issued2017
dc.date.submitted2017en
dc.description.abstractAPI 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 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 from API test code 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 for 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.en_US
dc.identifier.citationSohan, S. M. (2017). Automated Example Oriented REST API Documentation (Doctoral thesis, University of Calgary, Calgary, Canada). Retrieved from https://prism.ucalgary.ca. doi:10.11575/PRISM/25074en_US
dc.identifier.doihttp://dx.doi.org/10.11575/PRISM/25074
dc.identifier.urihttp://hdl.handle.net/11023/4244
dc.language.isoeng
dc.publisher.facultyGraduate Studies
dc.publisher.institutionUniversity of Calgaryen
dc.publisher.placeCalgaryen
dc.rightsUniversity of Calgary graduate students retain copyright ownership and moral rights for their thesis. You may use this material in any way that is permitted by the Copyright Act or through licensing that has been assigned to the document. For uses that are not allowable under copyright legislation or licensing, you are required to seek permission.
dc.subjectComputer Science
dc.subject.otherAPI
dc.subject.otherREST
dc.subject.otherWeb
dc.subject.otherDocumentation
dc.subject.otherSoftware
dc.subject.otherQualitative Study
dc.subject.otherControlled Study
dc.subject.otherCase Study
dc.titleAutomated Example Oriented REST API Documentation
dc.typedoctoral thesis
thesis.degree.disciplineComputer Science
thesis.degree.grantorUniversity of Calgary
thesis.degree.nameDoctor of Philosophy (PhD)
ucalgary.item.requestcopytrue
Files
Collections
Open Theses and Dissertations