Developer Perspectives on REST API Usability: A Study of REST API Guidelines

2026-01-23

AI Summary

This study addresses the challenge of effectively adopting REST API design guidelines, which are often too extensive or disconnected from real-world practice, thereby compromising API usability. Through semi-structured interviews with 16 industry experts, combined with qualitative analysis and case studies, the work systematically identifies eight key factors influencing API usability, underscoring the critical role of adhering to established conventions. The research reveals developer resistance to rigid guidelines and argues that effective design standards must evolve alongside organizational practices, involve broad stakeholder participation, and integrate automated linting to enhance compliance and design quality. Proposing an innovative “dynamic adaptation plus automated education” paradigm, this work offers both theoretical insights and practical foundations for developing actionable, context-aware API design guidelines.

Technology Category

• Humans and AI: User Experience and Usability
• Natural Language Processing: Safety and Robustness
• Philosophy and Ethics of AI: Safety, Robustness & Trustworthiness

Application Category

• User Modeling, Personalization and Recommendation: Metrics for user behavior and evaluating success
• Responsible Web: Consent frameworks and practices on the web
• Search and Retrieval-Augmented AI: Web evaluation methodologies and metrics

Abstract

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.

Problem

• REST API
• API usability
• design guidelines
• developer experience
• guideline adoption

Innovation

• REST API usability
• API design guidelines
• developer adoption
• automated linting
• empirical study