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.

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