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

• URL: http://arxiv.org/abs/2601.16705v1
• Date: Fri, 23 Jan 2026 12:45:01 GMT
• Title: Developer Perspectives on REST API Usability: A Study of REST API Guidelines
• Authors: Sven Peldszus, Jan Rutenkolk, Marcel Heide, Jan Sollmann, Benjamin Klatt, Frank Köhne, Thorsten Berger,
• Abstract summary: We present an interview study with 16 REST API experts from industry.<n>We identify eight factors influencing REST API usability, among which the adherence to conventions is the most important.
• Score: 4.2711788353513835
• License: http://arxiv.org/licenses/nonexclusive-distrib/1.0/
• 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.

Related papers

• Validating API Design Requirements for Interoperability: A Static Analysis Approach Using OpenAPI [0.0]
  API quality validation contributes to aligning technical designs with requirements and enterprise architecture.<n>S.E.O.R.A. facilitates early validation of non-functional API requirements.<n>It improves the API design process by automating checks that would otherwise require manual inspection.
  arXiv  Detail & Related papers  (2025-11-21T23:15:46Z)
• A Systematic Evaluation of Large Code Models in API Suggestion: When, Which, and How [53.65636914757381]
  API suggestion is a critical task in modern software development. Recent advancements in large code models (LCMs) have shown promise in the API suggestion task.
  arXiv  Detail & Related papers  (2024-09-20T03:12:35Z)
• WorldAPIs: The World Is Worth How Many APIs? A Thought Experiment [49.00213183302225]
  We propose a framework to induce new APIs by grounding wikiHow instruction to situated agent policies.<n>Inspired by recent successes in large language models (LLMs) for embodied planning, we propose a few-shot prompting to steer GPT-4.
  arXiv  Detail & Related papers  (2024-07-10T15:52:44Z)
• A Conceptual Framework for API Refactoring in Enterprise Application Architectures [0.0]
  We introduce a conceptual framework for the implementation of APIs. Our framework elicits that there are important trade-offs and choices, which significantly affect the efficiency, maintainability, and isolation properties of the resulting architecture. Our work also elicits, for the first time, how certain programming language features can reduce friction in applying API and open up more architectural choices.
  arXiv  Detail & Related papers  (2024-07-10T07:32:16Z)
• RESTRuler: Towards Automatically Identifying Violations of RESTful Design Rules in Web APIs [3.4711214580685557]
  We present RESTRuler, a Java-based open-source tool that uses static analysis to detect design rule violations in OpenAPI descriptions. For robustness, RESTRuler successfully analyzed 99% of the used real-world OpenAPI definitions. 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.
  arXiv  Detail & Related papers  (2024-02-21T11:25:22Z)
• Leveraging Large Language Models to Improve REST API Testing [51.284096009803406]
  RESTGPT takes as input an API specification, extracts machine-interpretable rules, and generates example parameter values from natural-language descriptions in the specification. Our evaluations indicate that RESTGPT outperforms existing techniques in both rule extraction and value generation.
  arXiv  Detail & Related papers  (2023-12-01T19:53:23Z)
• Exploring Behaviours of RESTful APIs in an Industrial Setting [0.43012765978447565]
  We propose a set of behavioural properties, common to REST APIs, which are used to generate examples of behaviours that these APIs exhibit. These examples can be used both (i) to further the understanding of the API and (ii) as a source of automatic test cases. Our approach can generate examples deemed relevant for understanding the system and for a source of test generation by practitioners.
  arXiv  Detail & Related papers  (2023-10-26T11:33:11Z)
• Adaptive REST API Testing with Reinforcement Learning [54.68542517176757]
  Current testing tools lack efficient exploration mechanisms, treating all operations and parameters equally. Current tools struggle when response schemas are absent in the specification or exhibit variants. We present an adaptive REST API testing technique incorporates reinforcement learning to prioritize operations during exploration.
  arXiv  Detail & Related papers  (2023-09-08T20:27:05Z)
• RestGPT: Connecting Large Language Models with Real-World RESTful APIs [44.94234920380684]
  A tool-augmented large language models (LLMs) have achieved remarkable progress in tackling a broad range of tasks. To address the practical challenges of tackling complex instructions, we propose RestGPT, which exploits the power of robustness. To fully evaluate RestGPT, we propose RestBench, a high-quality benchmark which consists of two real-world scenarios and human-annotated instructions.
  arXiv  Detail & Related papers  (2023-06-11T08:53:12Z)
• Do RESTful API Design Rules Have an Impact on the Understandability of Web APIs? A Web-Based Experiment with API Descriptions [4.26177272224368]
  We conducted a controlled Web-based hybrid experiment with 105 participants. We studied 12 design rules using API snippets in two versions: one that adhered to a "rule" and one that was a "violation" of this rule. For 11 of the 12 rules, we found that "violation" performed significantly worse than "rule" for the comprehension tasks.
  arXiv  Detail & Related papers  (2023-05-12T09:48:23Z)
• Evaluating Embedding APIs for Information Retrieval [51.24236853841468]
  We evaluate the capabilities of existing semantic embedding APIs on domain generalization and multilingual retrieval. We find that re-ranking BM25 results using the APIs is a budget-friendly approach and is most effective in English. For non-English retrieval, re-ranking still improves the results, but a hybrid model with BM25 works best, albeit at a higher cost.
  arXiv  Detail & Related papers  (2023-05-10T16:40:52Z)

This list is automatically generated from the titles and abstracts of the papers in this site.

This site does not guarantee the quality of this site (including all information) and is not responsible for any consequences.