Do RESTful API design rules have an impact on the understandability of Web APIs?
Open Access
- 26 September 2023
- journal article
- research article
- Published by Springer Nature in Empirical Software Engineering
- Vol. 28 (6) , 1-35
Abstract
Context: Web APIs are one of the most used ways to expose application functionality on the Web, and their understandability is important for efficiently using the provided resources. While many API design rules exist, empirical evidence for the effectiveness of most rules is lacking. Objective: We therefore wanted to study 1) the impact of RESTful API design rules on understandability, 2) if rule violations are also perceived as more difficult to understand, and 3) if demographic attributes like REST-related experience have an influence on this. Method: We conducted a controlled Web-based experiment with 105 participants, from both industry and academia and with different levels of experience. Based on a hybrid between a crossover and a between-subjects design, we studied 12 design rules using API snippets in two complementary versions: one that adhered to a rule and one that was a violation of this rule. Participants answered comprehension questions and rated the perceived difficulty. Results: For 11 of the 12 rules, we found that violation performed significantly worse than rule for the comprehension tasks. Regarding the subjective ratings, we found significant differences for 9 of the 12 rules, meaning that most violations were subjectively rated as more difficult to understand. Demographics played no role in the comprehension performance for violation. Conclusions: Our results provide first empirical evidence for the importance of following design rules to improve the understandability of Web APIs, which is important for researchers, practitioners, and educators.Keywords
Funding Information
- Universität Stuttgart
This publication has 30 references indexed in Scilit:
- Detection of REST Patterns and Antipatterns: A Heuristics-Based Approach2014
- RESTful Web Services: Principles, Patterns, Emerging Technologies2013
- Planning2012
- Today’s Top “RESTful” Services and Why They Are Not RESTfulLecture Notes in Computer Science, 2012
- Wilcoxon–Mann–Whitney Test2011
- Reporting Experiments in Software Engineering2008
- Principled design of the modern Web architectureACM Transactions on Internet Technology, 2002
- Multiple Hypothesis TestingAnnual Review of Psychology, 1995
- An Analysis of Variance Test for Normality (Complete Samples)Biometrika, 1965
- A NEW MEASURE OF RANK CORRELATIONBiometrika, 1938