PaperlayerView exact revision on arXiv

Source-linked AI summary

Detecting HTTP Status Code Misuses in REST APIs via Static and Dynamic Analysis

Alix Decrop, Andrea Arcuri, Mike Papadakis, Pierre-Yves Schobbens, Gilles Perrouin

arXiv:2609.12770v1cs.SE

TL;DR

HTTP status-code semantics are not enforced in REST APIs, and deviations can mislead API analysis and testing. The paper derives usage rules and applies static and dynamic analyzers; it reports that misuses are frequent and systematic, supporting complementary analysis and caution against relying on status codes alone.

  • Problem

    REST APIs can deviate from HTTP status-code semantics, and 5xx codes may be treated as bugs by fuzzing tools.

    Source: §1 · p. 1

  • Method

    The authors derive 30 usage rules from HTTP semantics and REST API principles, then implement static and dynamic analyzers.

    Source: §7 · p. 24

  • Results

    The authors find status-code misuses frequent and systematic in REST APIs and conclude that static and dynamic approaches should be used complementarily.

    Source: §7 · p. 24

  • Takeaways & Limitations

    REST API responses should be analyzed in depth, and users and testers should not rely solely on HTTP status codes.

    Source: §7 · p. 24

    Absence of a 200 response alone does not establish that an API is faulty.

    Source: §3.2 · p. 6

Abstract

from arXiv · show

REST APIs are widely used on the web for client-server communications. As REST is based on HTTP, server responses contain status codes to indicate the outcome of requests (e.g., 200 OK for a success and 404 Not Found for an unavailable resource). While HTTP status codes are standardized, their semantics are not enforced in REST, leading to many misuses in practice (e.g., using 500 Internal Server Error to describe a client error). Such misuses may have nefarious consequences, such as reducing interoperability, misleading API clients, or causing false positives in testing tools. In this paper, we present a combined static and dynamic analysis approach for detecting HTTP status code misuses in REST APIs. We first study 2,625 real-world REST API specifications to identify relevant status codes and derive a set of 30 usage rules based on HTTP standards and REST API principles. We then implement tools to identify such rule violations in OpenAPI specifications (static analysis) and in API behavior (dynamic analysis). Our evaluation finds that status code misuses are frequent and systematic in REST APIs, with both static and dynamic approaches detecting various misuses. We highlight that both approaches may be used in a complementary manner, and also provide insight for REST API testers and users alike.

1 Introduction

REST APIs communicate over HTTP, but their status-code use can deviate from HTTP semantics, which are not enforced in practice. The paper studies these misuses and contributes rules, a dataset, and complementary static and dynamic detection tools.

1 Introduction

  • Status-code misuses can confuse clients about whether an error comes from the client or server and mislead API analysis and testing tools.For example, 5xx codes may be treated as bugs by fuzzing tools, while generic codes can make invalid requests harder to debug.Source: §1 · pp. 1–2
  • The authors present static and dynamic analysis as complementary approaches to detecting REST API status-code misuses.The work also provides implementation and evaluation data.Source: §1 · p. 2
  • The evaluation dataset combines three REST API benchmarks and contains 2,625 distinct specifications and 36 API implementations.The current dataset expands an earlier set of 60 REST API specifications.Source: §1 · p. 2
  • The paper presents a study of how status codes are distributed across the REST APIs in its dataset, making status-code distribution the subject of its analysis.Source: §1 · p. 2
  • The authors derive 30 status-code usage rules from HTTP semantics and REST API principles.The rules refine and extend the 24 rules from preliminary work and are validated against additional sources.Source: §1 · p. 2
  • SCOAS statically detects status-code misuses in OpenAPI specifications.The tool builds on preliminary work and is improved with additional rules and a better implementation structure.Source: §1 · p. 2
  • An EvoMaster extension dynamically analyzes status-code misuses in REST API behavior, a focus absent from the preliminary work.The paper evaluates misuse detection with both SCOAS and EvoMaster.Source: §1 · p. 2

2 Background and Related Work

The section introduces REST APIs as HTTP-based services organized around resources and explains that standardized HTTP status-code semantics are not enforced in practice. It also reviews OpenAPI documentation, REST and HTTP conformance work, and API testing tools.

2.1 REST APIs and HTTP

  • REST is an architectural style for scalable, loosely coupled, interoperable services; REST APIs use HTTP to operate on URI-identified resources, and RESTful APIs implement or extend these principles.REST communication is stateless, with each request containing the information needed for server processing.Source: §2.1 · p. 2

2.2 HTTP Methods and Requests

  • GET retrieves data, POST commonly sends data for creation, PUT creates or updates, PATCH updates, and DELETE removes data from the server.POST, PUT, and PATCH requests usually carry the data to create or update in a payload.Source: §2.2 · p. 3

2.3 HTTP Status Codes

  • HTTP status codes communicate request outcomes, but their standardized semantics are not enforced in REST APIs, allowing misleading responses.The Deezer example returns 200 OK with an error body and a non-standard 600 code, potentially leading a client that trusts the status code to report a false positive.Source: §2.3 · p. 3

2.4 OpenAPI Specification

  • OpenAPI Specification (OAS) is a machine-readable standard for documenting REST APIs, including paths, methods, parameters, expected responses, and reusable components.Most state-of-the-art API testing tools require an OAS file as input.Source: §2.4 · p. 4

2.5.1 REST API Design Conformance.

  • REST API design-conformance research includes rule-based checks, while existing approaches may require source code, miss fine-grained misuses, or omit HTTP status-code semantics.Prior SCOAS work implemented 24 status-code rules and reported over 17,767 misuses across 60 specifications.Source: §2.5.1 · p. 5

2.5.2 HTTP Semantics Compliance.

  • HTTP conformance studies report a global lack of conformance across 9,990 web hosts and noncompliant network-middlebox implementations associated with RFC ambiguities.The cited work identifies 12 noncompliant implementations and notes potential vulnerabilities.Source: §2.5.2 · p. 5

2.5.3 REST API Testing Tools.

  • REST API fuzzers use an API's location, OpenAPI schema, and HTTP responses to choose endpoints and inputs, and can flag 500 responses or schema-response mismatches.Some fuzzers also perform security attacks to detect vulnerabilities.Source: §2.5.3 · p. 5

2.6 Terminology

  • In this paper, “API” abbreviates “REST API,” and “status code misuse” is used interchangeably with “status code usage rule violation.”“Dataset” and “specification” terminology is also used interchangeably in the paper.Source: §2.6 · p. 5

3 Approach

SCOAS checks OpenAPI response contexts against status-code usage rules, while EvoMaster checks status codes returned during fuzzing. The two analyses expose different kinds of problems and have different limits.

3.1 Static Analysis: SCOAS

  • SCOAS builds a context from each path, method, and response, then checks that context against the defined usage rules and records any violations.Rules may depend on path data, such as an {id} parameter, or method data, such as a GET request.Source: §3.1 · pp. 5–6
  • SCOAS reports execution totals and, for each violation, its route, response, parameters, rule information, and repair instructions.The report includes overall counts such as violations, average violations per route, and responses analyzed.Source: §3.1 · p. 6

3.2 Dynamic Analysis: EvoMaster

  • EvoMaster evaluates HTTP status-code semantics on each call made during fuzzing, including whether a returned code fits the request context.The authors report that integrating all defined HTTP oracles into the fuzzer took fewer than 100 lines of code.Source: §3.2 · pp. 6–8
  • Fuzzing can reveal faults but cannot prove their absence, and it cannot evaluate oracles that require a condition to be present in the schema.A fuzzer may also fail to generate inputs that reach a desired response, so treating the absence of a 200 response as an API fault can produce a false positive.Source: §3.2 · p. 6
  • A 201 Created response to a GET is a clear semantics fault, and dynamic analysis can detect it even when the OpenAPI schema does not declare that response.Such a response can also constitute a schema-mismatch fault; a schema can document a faulty response that the API never returns in practice.Source: §3.2 · pp. 6–7

4 Evaluation

The evaluation asks which status codes and usage rules are relevant, and how well static and dynamic analysis detect misuses. It uses three API datasets, with the dynamic-analysis evaluation restricted to WFD.

4.1 Research Questions

  • The four research questions cover relevant status codes, possible usage rules, and the effectiveness of static and dynamic misuse detection.Source: §4.1 · p. 8

4.2 Experimental Setup

  • The evaluation draws on APIs.guru, PRAB, and WFD, three state-of-the-art benchmarks assembled into a REST API dataset.The datasets may contain duplicate APIs or different versions; the authors retain possible duplicates because removing APIs could skew individual dataset results.Source: §4.2.1 · p. 8

4.2.1 Dataset and Benchmark.

  • All three datasets support the status-code and static-analysis questions, but only WFD is used for dynamic analysis because it is tailored to that setup.Source: §4.2.1 · p. 8

4.2.2 Environment.

  • Static evaluations ran offline with multiple executions to guard against external issues; EvoMaster experiments ran 15 at a time in parallel.Source: §4.2.2 · pp. 8–9

4.3 RQ.1: Relevant Status Codes for REST APIs

Across 2,625 OpenAPI specifications, the study finds common use of success and client-error codes alongside non-standard or unassigned codes that hinder reliance on HTTP semantics.

4.3 RQ.1: Relevant Status Codes for REST APIs

  • 200 OK was most prevalent, appearing in 100% of APIs in PRAB and WFD and 98% in APIs.guru.Source: §4.3 · p. 9
  • 400, 401, 403, and 404 were also prevalent, reflecting client-error uses for invalid requests, authentication, access restrictions, and invalid paths.The prevalence of 401 and 403 also suggests that many APIs use authentication mechanisms.Source: §4.3 · p. 10
  • 500 Internal Server Error appeared in all datasets and is prone to misuse as a generic error response regardless of whether the fault is client- or server-side.Source: §4.3 · p. 10
  • The OpenAPI keyword default appeared in all datasets and is valid for documenting responses, though the authors recommend specific status codes where possible.Source: §4.3 · p. 10
  • Non-standard or unassigned codes, including 480–485 and 0, appeared in the datasets; these codes provide no HTTP semantic information for clients.The 5XX label also appeared in APIs.guru and PRAB, though it denotes a range rather than an exact status code.Source: §4.3 · p. 10
  • 2,625 OpenAPI specifications contained 369,580 responses and 128 distinct status codes across the three datasets.The datasets comprised 2,529 APIs.guru specifications, 60 PRAB specifications, and 36 WFD specifications.Source: §4.3 · pp. 9–10

4.4 RQ.2: Defining Status Code Usage Rules

The paper derives REST API status-code usage rules by combining HTTP standards, REST API principles, and observed status-code distributions. The resulting 30 rules identify both required status codes that are missing and non-applicable codes that are implemented.

4.4 RQ.2: Defining Status Code Usage Rules

  • The authors analyzed IANA’s official HTTP Status Code Registry; most status-code references redirect to RFC 9110, while RFC 5789 is also used as a reference for rules related to PATCH.Source: §4.4 · pp. 10–11
  • Massé’s REST design guidance is cross-checked against relevant RFC sections before its rules are adapted to OpenAPI contexts.For example, the 404 rule is formalized for cases where a client URI cannot map to a resource.Source: §4.4 · p. 12
  • The analysis defines 30 unique status-code usage rules for REST APIs from HTTP standards, REST API principles, and status-code distributions.The rules are grouped into checks for required codes that are missing and non-applicable codes that are implemented.Source: §4.4 · p. 12

4.5 RQ.3: Static Analysis of Status Code Misuses in REST APIs

Static analysis of 2,612 OpenAPI specifications found 696,891 status-code rule violations, with misuses in 99.92% of specifications. Missing client-error responses were especially common, alongside security-related and less frequent but more severe semantic misuses.

4.5.1 Status Code Misuse Prevalence.

  • Missing client-error responses for specific contexts were frequent, especially the absent 422 response when parameters are present.The most frequent rule violation across the three datasets was has-422-if-params.Source: §4.5.1 · p. 14
  • The results point to broadly under-documented client errors, including missing 400, 413, and 404 responses for relevant request contexts.Examples include query parameters, a Content-Length header, and a path parameter.Source: §4.5.1 · p. 14
  • The most frequent missing success response was 204 No Content when a response has no content, across all three datasets.The authors suggest APIs may omit documenting response content or incorrectly use 204.Source: §4.5.1 · p. 14
  • Security-related violations included 401 responses without the required WWW-Authenticate header, suggesting developers often omit that header from documentation.This misuse was identified as no-401-if-no-www-authenticate.Source: §4.5.1 · p. 14
  • Less frequent but more severe violations included missing 200 responses for GET, 201 responses for PATCH, and non-standard status codes.The authors characterize these as misunderstandings of HTTP semantics, while noting they occurred less often.Source: §4.5.1 · p. 14
  • Across 2,612 distinct OpenAPI specifications, SCOAS found 696,891 status-code misuses; misuses appeared in 99.92% of specifications, with only two containing none, revealing their prevalence in REST APIs.Source: §4.5.1 · p. 16

4.6 RQ.4: Dynamic Analysis of Status Code Misuses in REST APIs

The authors implemented dynamic checks for a subset of status-code rules in EvoMaster and tested them on 36 WFD APIs. The checks detected hundreds of faulty endpoints across eight fault types, while framework behavior constrained testing of some rules.

4.6 RQ.4: Dynamic Analysis of Status Code Misuses in REST APIs

  • Of the 30 static rules, 16 could be translated into dynamic checks, with some static checks not directly transferable to API behavior.The implemented rules and their required inputs are listed in Table 3.Source: §4.6 · p. 16, Table 3 · p. 17
  • The implementation was verified with an artificial API containing a faulty endpoint for each of the 16 rules, and the injectable faults were reliably detected except two.Faults involving a body with status 204 or 205 could not be produced in SpringBoot with its default Tomcat server, which silently removes the payload.Source: §4.6 · p. 17
  • EvoMaster uses Jersey1 for HTTP requests; Jersey crashes with an exception below status 100 but returns a response object without exception at 600 or above, while RestAssured crashes in both cases.HTTP specifications can be interpreted differently between libraries and frameworks.Source: §4.6 · p. 17
  • Dynamic checks ran on 36 WFD APIs for one hour each in white-box mode, with each experiment repeated 10 times for 360 runs.The authors did not inject faults into these APIs; the detected faults were real and previously unknown to them.Source: §4.6 · pp. 17–18
  • Generated tests exposed a GET endpoint returning 201 Created, although the authors say its apparent behavior would better fit POST.They note this mismatch has functional consequences because GET is idempotent.Source: Figure 11 · p. 19, §4.6 · p. 19
  • Generated tests flagged ohsome-api returning 413 Content Too Large for a request with no body, although 413 is meant for oversized request contents; another flagged 501 for an implemented endpoint.Source: §4.6 · p. 19, Figure 13 · p. 20
  • A generated test also found a 401 response without the mandatory WWW-Authenticate header.The example came from the familie-ba-sak API.Source: Figure 14 · p. 21, §4.6 · p. 21
  • The experiment detected hundreds of faulty endpoints spanning eight of the 16 dynamically checked fault types.Fault counts were based on distinct path-and-verb endpoints that triggered a rule.Source: §4.6 · pp. 18, 19, 21

5 Discussion

The discussion argues that static and dynamic analysis cover different views of status-code use: API specifications and deployed behavior. It also describes consequences of misuse for testing tools and API users.

5.1 Static and Dynamic Analysis Value

  • Static analysis can flag potential misuses in specifications without execution, but cannot establish whether documented responses are implemented; dynamic analysis observes implementation behavior and can find undocumented responses.The authors therefore argue for complementing the approaches to cover both the intended contract and actual implementation.Source: §5.1 · p. 22

5.2 Implications for API Testers

  • Status-code misuse can produce false bug reports because REST API testing tools use 5xx responses to identify server errors.The authors recommend deeper response analysis, including parsing messages and configuring mappings for API-defined codes.Source: §5.2 · pp. 22–23

5.3 Implications for API Users

  • Misleading status codes can confuse API clients, propagate invalid responses between services, and make invalid requests harder to debug.The authors recommend that clients check API documentation and analyze response content rather than trusting status codes alone.Source: §5.3 · p. 23

6 Threats to Validity

The authors identify threats from subjective rule construction and possible tool defects, limited dataset and format coverage, and a misuse definition that may miss context-dependent interpretations.

6.1 Internal Validity

  • Rule ground truth may reflect human error or disagreement about misuse, while tool implementations may contain bugs; validation, testing, and output cross-checking mitigate these threats.The rules were derived through manual analysis and checked against official IANA HTTP standards.Source: §6.1 · pp. 23–24

6.2 External Validity

  • The benchmark may not represent all real-world APIs, analyzed specifications may be outdated, and the static analysis covers OpenAPI rather than other documentation formats.The authors used three datasets varying in popularity, size, and application domain to mitigate representativeness concerns.Source: §6.2 · p. 24

6.3 Construct Validity

  • The misuse definition may omit context-dependent or domain-specific interpretations, introducing subjectivity into the evaluation.Source: §6.3 · p. 24

7 Conclusion and Future Work

The paper develops 30 status code usage rules and static and dynamic analyzers, then evaluates them across three REST API benchmarks. The evaluation finds misuses frequent and systematic, supporting complementary analysis and deeper response inspection by API users and testers.

Conclusion

  • The authors developed 30 status code usage rules from HTTP semantics and REST API principles, operationalized in SCOAS and an EvoMaster extension.The evaluation dataset combines APIs.guru, PRAB, and WFD benchmarks.Source: §7 · p. 24
  • Status code misuses are frequent and systematic in REST APIs, and static and dynamic approaches should be used complementarily.Source: §7 · p. 24
  • API users and testers should analyze REST API responses in depth rather than rely solely on HTTP status codes.Source: §7 · p. 24

Future Work

  • Automatically fixing missing status codes is challenging because valid responses may depend on context known only by the developer.For a GET request, a missing success code could be 200 OK, 204 No Content, or both; implementation context may make automated repair feasible.Source: §7 · p. 24
  • Future work includes assessing the security implications of status code misuses, including in microservice systems.Source: §7 · p. 24

Disclosure

The authors report no relevant competing interests and disclose limited generative AI use for rephrasing, with the authors reviewing and taking responsibility for the final content.

Disclosure

  • The authors declare no relevant competing interests and report limited generative AI use for rephrasing, followed by author review and responsibility for the final content.Source: Disclosure · p. 25
Loading 2609.12770v1…