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 crossover 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.

翻译：背景：Web API是网络上暴露应用程序功能最常用的方式之一，其可理解性对于高效使用所提供的资源至关重要。尽管存在许多API设计规则，但大多数规则有效性的实证证据仍显不足。目标：因此，我们希望研究：1）RESTful API设计规则对可理解性的影响；2）违反规则是否会被感知为更难理解；3）人口统计学特征（如REST相关经验）是否对此产生影响。方法：我们开展了一项受控的Web实验，共有105名来自工业界和学术界、具有不同经验水平的参与者参与。基于交叉设计，我们使用API代码片段研究了12条设计规则的两个互补版本：一个遵循"规则"，另一个违反该"规则"。参与者需回答理解性问题并评估其感知难度。结果：在12条规则中，有11条规则中"违反"版本的理解任务表现显著差于"规则"版本。关于主观评价，12条规则中有9条存在显著差异，意味着大多数违反规则被参与者主观评价为更难理解。人口统计学特征对"违反"版本的理解表现没有影响。结论：我们的结果为遵循设计规则以提高Web API可理解性的重要性提供了首批实证证据，这对研究人员、从业者和教育工作者均具有重要意义。