RESTful APIs based on HTTP are one of the most important ways to make data and functionality available to applications and software services. However, the quality of the API design strongly impacts API understandability and usability, and many rules have been specified for this. While we have evidence for the effectiveness of many design rules, it is still difficult for practitioners to identify rule violations in their design. We therefore present RESTRuler, a Java-based open-source tool that uses static analysis to detect design rule violations in OpenAPI descriptions. The current prototype supports 14 rules that go beyond simple syntactic checks and partly rely on natural language processing. The modular architecture also makes it easy to implement new rules. To evaluate RESTRuler, we conducted a benchmark with over 2,300 public OpenAPI descriptions and asked 7 API experts to construct 111 complicated rule violations. For robustness, RESTRuler successfully analyzed 99% of the used real-world OpenAPI definitions, with some failing due to excessive size. For performance efficiency, the tool performed well for the majority of files and could analyze 84% in less than 23 seconds with low CPU and RAM usage. Lastly, for effectiveness, RESTRuler achieved a precision of 91% (ranging from 60% to 100% per rule) and recall of 68% (ranging from 46% to 100%). Based on these variations between rule implementations, we identified several opportunities for improvements. While RESTRuler is still a research prototype, the evaluation suggests that the tool is quite robust to errors, resource-efficient for most APIs, and shows good precision and decent recall. Practitioners can use it to improve the quality of their API design.

翻译：基于HTTP的RESTful API是向应用程序和软件服务提供数据与功能的重要方式之一。然而，API设计的质量严重影响其可理解性与可用性。为此，学术界和工业界已制定了诸多设计规则。尽管已有证据表明众多设计规则具有良好效果，但实践者仍难以识别其设计中的规则违反情况。为此，我们提出RESTRuler——一款基于Java的开源工具，通过静态分析检测OpenAPI描述中的设计规则违反。当前原型支持14项规则，这些规则超越简单语法检查，部分依赖自然语言处理技术。其模块化架构也便于实现新规则。为评估RESTRuler，我们构建了包含2300余个公开OpenAPI描述的基准数据集，并邀请7位API专家构造了111个复杂规则违反案例。在鲁棒性方面，RESTRuler成功分析了99%的真实OpenAPI定义（部分失败案例源于文件规格过大）；在性能效率方面，该工具对多数文件表现优异，84%的文件可在23秒内完成分析且CPU与内存占用较低；在有效性方面，RESTRuler实现了91%的精确率（各规则区间为60%-100%）与68%的召回率（各规则区间为46%-100%）。基于不同规则实现间的性能差异，我们识别出若干改进方向。尽管RESTRuler仍属研究原型，但评估表明该工具具有较强容错性、面向多数API的资源高效性，以及良好的精确率与可接受的召回率。实践者可利用其提升API设计质量。