HTTP REST API Learning (HRAL)

• HTTP REST API Learning is an unsupervised anomaly detection approach that extracts API endpoint structures from network traffic and recovers detailed OpenAPI specifications.
• It employs hierarchical clustering and path-parameter inference to model endpoint patterns and schema constraints from benign request traffic.
• HRAL integrates structural anomaly detection with signature-based rules to effectively flag potential attacks in partially documented API environments.

HTTP REST API Learning (HRAL) is an unsupervised anomaly detection approach for API security that models the structure and behavior of HTTP REST API endpoints directly from network traffic, without relying on predefined rules or documentation. In the reported formulation, HRAL learns a specification from benign request traffic, treats requests matching the learned structure as normal, and flags deviations as potential attacks. The method is presented as a way to recover fine-grained OpenAPI specifications from traffic alone and to use the resulting specification as a foundation for anomaly-based detection in partially documented API environments (Dubin et al., 2 Jul 2026).

1. Problem formulation and security objective

HRAL is defined around anomaly-based API security. The task is to learn the normal structure of an HTTP REST API from observed request traffic and then identify requests that deviate from that learned structure. The paper formalizes the observed request set as $R = \{r_1, r_2, \dots, r_N\}$, where each request $r_i = (p_i, q_i, h_i, b_i)$ comprises a request path $p_i \in \Sigma^+$, a query-parameter multiset $q_i$, a header set $h_i$, and an optional body $b_i$ (Dubin et al., 2 Jul 2026).

The learned target is an API specification $\mathcal{T} = \{\tau_1, \dots, \tau_K\}$, where each endpoint template $\tau_j = (P_j, \mathcal{S}_j)$ consists of a path pattern $P_j = (s_1, s_2, \dots, s_L)$ and a schema $\mathcal{S}_j$. In this formulation, path segments are either static literals or parameter placeholders, while the schema defines types, regex patterns, and length constraints for each parameter or field. The matching function $r_i = (p_i, q_i, h_i, b_i)$0 is defined so that a request matches a template when its tokenized path conforms to the path pattern and its other fields satisfy the schema (Dubin et al., 2 Jul 2026).

The detector itself is defined as $r_i = (p_i, q_i, h_i, b_i)$1:

$r_i = (p_i, q_i, h_i, b_i)$2

$r_i = (p_i, q_i, h_i, b_i)$3

Under this convention, $r_i = (p_i, q_i, h_i, b_i)$4 denotes a request accepted as normal and $r_i = (p_i, q_i, h_i, b_i)$5 denotes an anomalous request. The objective is to learn $r_i = (p_i, q_i, h_i, b_i)$6 from a benign training set $r_i = (p_i, q_i, h_i, b_i)$7 so as to minimize false negatives and false positives on a held-out test set $r_i = (p_i, q_i, h_i, b_i)$8 containing both benign and attack requests (Dubin et al., 2 Jul 2026).

2. Inducing API structure from raw traffic

HRAL induces an API specification from raw HTTP traffic via hierarchical clustering and path-parameter inference. The first stage is preprocessing and vectorization. Each request path and the header and query names are tokenized, and tokens are stemmed via Porter stemmer. The resulting request representation is a count vector $r_i = (p_i, q_i, h_i, b_i)$9 obtained by counting stemmed tokens in the path, query keys, and header keys (Dubin et al., 2 Jul 2026).

The clustering stage groups feature vectors into clusters $p_i \in \Sigma^+$0, each intended to correspond to one API endpoint. HRAL uses agglomerative clustering with Ward’s linkage, merging the pair of clusters that minimizes the increase in total within-cluster sum of squared errors:

$p_i \in \Sigma^+$1

Merging continues until the minimum inter-cluster distance exceeds the threshold $p_i \in \Sigma^+$2. This choice makes clustering the dominant computational component of the pipeline (Dubin et al., 2 Jul 2026).

Path-parameter inference is then performed independently for each cluster. HRAL collects the request paths in the cluster, aligns token positions, and marks a token position as static when all paths share the same literal string at that position. Otherwise, the position is declared a parameter placeholder. For each inferred parameter, HRAL gathers the length distribution and character-class pattern of observed values, then computes a tight regex from min/max length and character sets. This yields both a parameterized path pattern and schema statistics for endpoint definition (Dubin et al., 2 Jul 2026).

The learned structures are integrated with Speculator. HRAL feeds the raw clustered requests into the Speculator engine to generate a baseline OpenAPI draft, then overrides its path definitions with the parameterized patterns $p_i \in \Sigma^+$3 and attaches the collected schema statistics $p_i \in \Sigma^+$4. The output is described as $p_i \in \Sigma^+$5, a full-detail OpenAPI spec (Dubin et al., 2 Jul 2026).

3. Algorithms, complexity, and induced specification semantics

The core algorithm is presented as Build_HRAL_Spec(R, δ): preprocess and vectorize requests, perform agglomerative clustering with Ward linkage and threshold $p_i \in \Sigma^+$6, infer a path pattern and schema for each cluster, call Speculator to build a baseline specification, and then replace path and schema definitions with the HRAL-derived ones before returning the modified specification (Dubin et al., 2 Jul 2026).

The resulting specification is not merely a flat endpoint inventory. It includes parameterized path definitions, along with schema-level constraints such as types, regex patterns, and length constraints. Because endpoint membership is derived from clustered traffic rather than from manually authored OpenAPI files, the learned specification is directly tied to observed usage. A plausible implication is that HRAL is best understood as traffic-induced structure learning rather than documentation recovery in the conventional authoring sense.

The complexity analysis emphasizes the cost of clustering. Let $p_i \in \Sigma^+$7, $p_i \in \Sigma^+$8 be the average request token length, and $p_i \in \Sigma^+$9 the vocabulary size. Vectorization runs in $q_i$0 time and $q_i$1 space using a sparse representation. Agglomerative clustering requires $q_i$2 time and $q_i$3 space for the full distance matrix, using scikit-learn’s optimized $q_i$4 variant. Path inference requires $q_i$5 time and $q_i$6 space for storing paths. Overall complexity is therefore $q_i$7 time and $q_i$8 space, dominated by clustering (Dubin et al., 2 Jul 2026).

This computational profile is significant because it frames HRAL as a method whose fidelity depends on traffic-derived granularity but whose scalability is constrained primarily by pairwise clustering costs. The paper does not propose an alternative asymptotic regime; consequently, the clustering stage remains the central algorithmic bottleneck.

4. Evaluation protocol and quantitative results

The evaluation uses the ATRDF dataset, attributed to Aharon et al. 2025. The dataset contains 18 REST endpoints, 108 252 normal requests, and 109 277 malicious requests across 7 vector types: Cookie Injection, Directory Traversal, Log Forging, LOG4J, RCE, SQL Injection, and XSS (Dubin et al., 2 Jul 2026).

Three levels of OpenAPI documentation detail are used for comparison. “Minimal” contains only parameter names and general types. “Basic” adds simple regex patterns. “Full” adds min/max length and stricter patterns. Performance is reported with Precision, Recall, and $q_i$9, defined as

$h_i$0

The main reported results are averaged over all attack types (Dubin et al., 2 Jul 2026).

Method	Recall	F1
Minimal OpenAPI	22.94	22.94
Basic OpenAPI	72.30	72.30
Full OpenAPI	93.57	93.57
Speculator	23.84	23.84
HRAL	82.07	87.24

These numbers establish the central empirical claim: HRAL achieves an average recall of 82.07% and an $h_i$1-score of 87.24%, and it significantly outperforms alternatives when API documentation is limited (Dubin et al., 2 Jul 2026). At the same time, the “Full OpenAPI” setting reaches 93.57 for both Recall and $h_i$2, so HRAL does not exceed the best fully specified documentation regime. The reported interpretation is therefore comparative rather than absolute: HRAL approaches the effectiveness of full API document definitions while removing the dependency on predefined rules or documentation (Dubin et al., 2 Jul 2026).

5. Hybrid detection with signature-based rules

A central limitation identified in the paper is that some attacks conform to learned endpoint schemas and therefore evade structural anomaly detection. The paper gives the specific example of LOG4J in request bodies: a payload can respect the learned path and schema, producing $h_i$3 even though the request is malicious (Dubin et al., 2 Jul 2026).

To address this, HRAL is combined with a signature engine such as the OWASP ModSecurity CRS. The paper defines

$h_i$4

The hybrid decision rule is

$h_i$5

In the examples given, a LOG4J payload in a JSON body respects the learned path/schema, so $h_i$6, but the OWASP signature engine flags it, yielding $h_i$7 and thus $h_i$8. Conversely, a structurally malformed or new endpoint request is detected by HRAL directly, so $h_i$9 and $b_i$0 (Dubin et al., 2 Jul 2026).

Empirically on ATRDF, the hybrid detector achieves 100% recall and 100% $b_i$1 across all seven attack types in a controlled evaluation. The paper further states the formal coverage condition

$b_i$2

This is important for interpreting what HRAL is and is not. A common misconception would be to treat traffic-induced structural learning as sufficient for complete API attack detection. The reported results indicate instead that HRAL is highly effective as a structural anomaly detector, but that signature-based rules remain necessary for attacks whose maliciousness is not expressed as a deviation from endpoint structure or learned schema (Dubin et al., 2 Jul 2026).

6. Position within REST API research

HRAL belongs to a broader line of work on REST APIs, OpenAPI specifications, and automated testing, but its operating assumptions differ from several adjacent approaches. “You Can REST Now: Automated Specification Inference and Black-Box Testing of RESTful APIs with LLMs” introduces RESTSpecIT, which requires an API name and an LLM key, uses a zero-shot, in-context masking strategy with GPT-3.5, and infers partial OpenAPI specifications while generating black-box tests that can uncover undocumented routes, parameters, and server errors (Decrop et al., 2024). “Exploring Behaviours of RESTful APIs in an Industrial Setting” derives behavioural properties such as B1–B4 from an OpenAPI document to generate worked examples and tests, emphasizing CRUD patterns, idempotency, and state restoration from specification-level information (Karlsson et al., 2023). “APIRL: Deep Reinforcement Learning for REST API Fuzzing” formulates REST API fuzzing as a Markov decision process and uses a DQN with a frozen RoBERTa embedding of API responses to learn mutation policies for testing documented operations (Foley et al., 2024). More generally, OpenAPI is described as a widely adopted RESTful API description language used to provide a structured description of RESTful web APIs for both human and automated machine processing (Malakhov et al., 2018).

This suggests that HRAL occupies a distinct position in the landscape. Rather than assuming a correct OpenAPI specification, deriving examples from one, or inferring one from an API name with a LLM, HRAL learns endpoint structure and schema constraints from traffic alone and then uses the induced specification as the basis for anomaly detection (Dubin et al., 2 Jul 2026). In that sense, HRAL connects API specification learning with API security, especially in partially documented environments.

Its broader significance follows directly from that positioning. Where prior tooling frequently depends on an existing or externally inferred description, HRAL treats network traffic itself as the primary evidence for endpoint discovery and parameter regularity. The paper therefore frames HRAL as a practical, documentation-free foundation for modern API security, with the caveat that full detection in the reported benchmark is achieved only when structural learning is augmented by signature-based rules (Dubin et al., 2 Jul 2026).