REST is today's most widely used architectural style for providing web-based services. In the age of service-orientation (a.k.a. Software as a Service (SaaS)) APIs have become core business assets and can easily expose hundreds of operations. While well-designed APIs contribute to the commercial success of a service, poorly designed APIs can threaten entire organizations. Recognizing their relevance and value, many guidelines have been proposed for designing usable APIs, similar to design patterns and coding standards. For example, Zalando and Microsoft provide popular REST API guidelines. However, they are often considered as too large and inapplicable, so many companies create and maintain their own guidelines, which is a challenge in itself. In practice, however, developers still struggle to design effective REST APIs. To improve the situation, we need to improve our empirical understanding of adopting, using, and creating REST API guidelines. We present an interview study with 16 REST API experts from industry. We determine the notion of API usability, guideline effectiveness factors, challenges of adopting and designing guidelines, and best practices. We identified eight factors influencing REST API usability, among which the adherence to conventions is the most important one. While guidelines can in fact be an effective means to improve API usability, there is significant resistance from developers against strict guidelines. Guideline size and how it fits with organizational needs are two important factors to consider. REST guidelines also have to grow with the organization, while all stakeholders need to be involved in their development and maintenance. Automated linting provides an opportunity to not only embed compliance enforcement into processes, but also to justify guideline rules with educational explanations.

翻译：REST是当今最广泛采用的Web服务架构风格。在服务导向时代（亦称软件即服务SaaS时代），API已成为核心商业资产，单个API可轻松暴露数百个操作接口。设计精良的API能促进服务商业成功，而设计拙劣的API可能危及整个组织。鉴于其重要价值，业界已提出诸多类似设计模式与编码规范的API可用性设计指南，例如Zalando与微软发布的流行REST API规范。然而这些规范常因体量庞大且适用性不足而被诟病，导致众多企业自主创建维护专属规范，这本身即构成重大挑战。实践中，开发者仍难以设计出高效的REST API。为改善现状，亟需深化对REST API规范采纳、使用及创建过程的实证认知。本研究通过对16位业界REST API专家进行深度访谈，系统阐释了API可用性内涵、规范有效性影响因素、规范采纳与设计挑战及最佳实践。研究发现影响REST API可用性的八大因素，其中遵循行业惯例最为关键。尽管设计规范确实能有效提升API可用性，但开发者对严格规范存在显著抵触情绪。规范体量及其与组织需求的适配度是两个需要重点考量的因素。REST规范需伴随组织发展持续演进，且所有利益相关方都应参与其开发维护过程。自动化代码检测不仅为规范合规性嵌入流程提供了技术路径，更能通过教育性解释为规范条款提供合理性支撑。