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

TL;DR

The paper investigates REST API usability and guideline practices through a qualitative interview study with 16 industry experts, aiming to understand what makes REST APIs usable, how guidelines are adopted, and why organizations create custom guidelines. It identifies eight factors influencing usability, with adherence to conventions as the most important, and highlights tensions between guideline enforcement and developer autonomy. The study shows that while guidelines are widely used, their effectiveness is limited by size, context-fit, and maintenance, and it emphasizes automation (e.g., linting/OpenAPI-driven checks) and interactive guidelines as promising improvements. Practically, the findings guide organizations to tailor guideline scope, involve stakeholders, and embed guideline enforcement into workflows, balancing consistency with autonomy and agility.

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.

Figures (5)

• Figure 1: Illustration of inconsistently designed REST APIs
• Figure 2: Factors influencing the usability of a REST API
• Figure 3: Best practices for designing usable REST APIs
• Figure 4: Factors influencing REST API guideline adoption
• Figure 5: Challenges to the creation of custom guidelines