Enhancing RAMOSE, a framework for implementing REST APIs and semantic-actionable outputs over data sources

Source: arXiv:2607.11218 · Published 2026-07-13 · By Arcangelo Massari, Sergei Slinkin, Ivan Heibi, Silvio Peroni

TL;DR

This paper addresses the practical challenges of implementing interoperable REST APIs over heterogeneous scholarly data sources, particularly those that align with the Scientific Knowledge Graph - Interoperability Framework (SKG-IF) standard. The authors present RAMOSE (RESTful API Manager Over SPARQL Endpoints) version 2, an open-source Python framework designed to convert declarative configuration files into fully documented REST APIs over RDF triplestores and other data sources. The second major release significantly extends RAMOSE by supporting query orchestration across multiple SPARQL endpoints and non-RDF sources, advanced result joining, pagination, caching, write operations with authentication, and OpenAPI specification export. A built-in module packages SKG-IF-specific filters and output formats to ease standard-compliant endpoint deployment. The framework’s unique ability to join RDF and non-RDF results on arbitrary keys within a single API operation was demonstrated through functional comparison with nine similar tools. RAMOSE powers the high-traffic OpenCitations REST APIs and underpins the GRAPHIA project’s SKG-IF federation.

Key findings

• RAMOSE v2 implements nine new requirements, including multi-source query orchestration and joining results across SPARQL and non-RDF endpoints.
• A declarative configuration plus optional Python addons can produce customized output formats, request parameters, caching, pagination, and OpenAPI exports.
• RAMOSE uniquely supports joining RDF and non-RDF query results on arbitrary keys within one API operation compared to nine evaluated similar tools.
• RAMOSE serves the OpenCitations REST APIs which handled nearly 38 million monthly requests from May 2025 to May 2026.
• The framework supports write operations (POST, PUT, DELETE) with bearer-token authentication both for clients and to protected backend endpoints.
• Pagination supports both simple row-based and entity-aware schemes, with caching managed via SQLite for configurable expiry.
• SPARQL Anything integration allows flexible querying of heterogeneous sources such as JSON, CSV, XML, HTML, Excel, binary files, and others.
• The SKG-IF module packages reusable filters and the JSON-LD output format, drastically lowering adoption effort for compliant endpoints.

Threat model

The threat model assumes an adversary that can send arbitrary HTTP requests to the provided REST APIs. Write operations are restricted to authenticated clients possessing valid bearer tokens; unauthorized attempts are rejected with HTTP 401 responses. The framework also supports authenticating itself to data sources requiring credentials. The adversary cannot bypass token checks or gain unauthorized access via the APIManager. The system does not address advanced attacker capabilities such as token theft or server compromise.

Methodology — deep read

1. Threat Model & Assumptions: RAMOSE assumes a client-server model where the client makes HTTP requests to REST API endpoints backed by SPARQL endpoints or other data sources. The main adversary handling is restricting write operations only to authenticated clients with bearer tokens. Read-only APIs remain open. RAMOSE protects data-modifying operations by authenticating callers using token checks before executing potentially harmful updates. The data sources themselves may require credentials. Compromises of tokens or endpoints are out of scope.

2. Data: The framework operates over RDF triplestores exposed as SPARQL endpoints and non-RDF data sources (CSV, JSON, XML, etc.). Provenance includes OpenCitations datasets (Meta and Index endpoints), public SPARQL endpoints, and heterogeneous data files accessed with SPARQL Anything. The framework itself does not hold data; it mediates queries and manipulates results.

3. Architecture / Algorithm: RAMOSE is implemented as a Python package structuring components into APIManager for request routing and operation dispatch, Operation objects for processing pipelines, add-on modules for output formats and filters, a SQLite-based ResultCache for caching query results, and TokenStore for bearer token management. Operations are defined by declarative configuration files in hash-format (.hf) or YAML syntax, containing SPARQL queries interleaved with new @@ directives to control endpoint selection (@@with), values injection (@@values), joins (@@join), iteration (@@foreach), pagination (@@page), and result filtering. Where multiple sources are involved, query orchestration first individually executes discrete queries against each source, then joins the tabular row results into an accumulator based on configurable keys and join types (inner or left).

Output format handling is extensible via addon modules mapping internal CSV-style tables into JSON-LD, XML, custom JSON, or RDF serializations. Custom request parameters can be declared either procedurally in Python or declaratively in YAML, enabling domain-specific filters (e.g., SKG-IF filter vocabulary) that modify queries or post-process results. The OpenAPI 3.2 specification is generated dynamically from the configuration, reflecting custom parameters, output media types, and authentication requirements.

Write operations are enabled by declaring SPARQL 1.1 update queries executed against dedicated update endpoints. Authentication enforces that only valid bearer tokens can access write operations. RAMOSE supports passing through credentials to backend endpoints using environment variables or CLI configuration.

4. Training Regime: Not applicable.

5. Evaluation Protocol: The authors conducted functional comparisons against nine similar open-source REST API frameworks, focusing on multi-source querying and result joining capabilities. They tested RAMOSE in production at OpenCitations, monitoring statistics for nearly 38 million monthly requests. Examples of configurations and operations demonstrate handling of complex queries spanning multiple RDF and non-RDF sources with graceful retry and caching. The effectiveness of pagination, caching, filtering, and authentication was verified through integration tests. Compatibility with SKG-IF requirements was assessed by implementing compliant endpoints using the built-in module.

6. Reproducibility: RAMOSE is open source and distributed via PyPI with a comprehensive documentation site, continuous integration testing, and semantic versioning. Configuration files defining API operations are human-readable and exportable as OpenAPI specifications. However, some backend datasets (e.g., OpenCitations triplestores) may not be fully public or frozen, which could limit exact replication. While the paper provides detailed code listings, no explicit frozen weights or closed datasets apply as this is a middleware engineering framework rather than ML.

Technical innovations

• Integration of multi-source query orchestration allowing sequential querying of distinct SPARQL and non-RDF endpoints, with post-query joining on arbitrary keys rather than relying on fragile federated SPARQL SERVICE calls.
• Introduction of @@ directives in declarative configuration files to control source selection, joins, value injection, iteration, pagination, and removal for flexible API operation pipelines.
• Extensible output formatting system supporting pluggable converters, including a built-in SKG-IF JSON-LD module that bundles compliant filters and serialization.
• Cache management at the post-processing stage using SQLite to speed up repeated identical queries, with cache invalidation triggered automatically upon successful write operations.
• Token-based authentication layer allowing fine-grained protection of write operations and passing authentication credentials to protected data endpoints.

Datasets

• OpenCitations Meta — Millions of bibliographic records — Public SPARQL endpoint
• OpenCitations Index — Citation data linked to the Meta set — Public SPARQL endpoint
• Various non-RDF sources in formats JSON, CSV, XML, HTML, Excel, etc. through SPARQL Anything

Baselines vs proposed

• Comparison against nine similar REST API frameworks: RAMOSE was the only tool capable of joining RDF and non-RDF query results on arbitrary keys within a single operation.
• OpenCitations REST APIs served nearly 38 million monthly requests (May 2025–May 2026) demonstrating scalability and production viability over large, heterogeneous scholarly datasets.

Figures from the paper

Figures are reproduced from the source paper for academic discussion. Original copyright: the paper authors. See arXiv:2607.11218.

Fig 3: Monthly requests to the OpenCitations REST APIs between May

Fig 4: Geographic distribution by country of the HTTP requests received

Limitations

• The reliance on separate queries joined post-hoc may not achieve the performance of tightly integrated federated queries, especially under heavy load or with high latency endpoints.
• RAMOSE’s caching strategy assumes immutable underlying data until explicitly updated—stale data may be served if write operations occur outside the API.
• Security model is limited to bearer tokens for write authentication; does not discuss more advanced authorization or protection against sophisticated adversaries.
• The performance and robustness of query orchestration in extreme failure or network partition scenarios is not fully evaluated.
• The framework does not natively handle streaming or incremental updates; full queries and joins must be re-executed or cached.
• Some backend sources may restrict federated queries or impose rate limits, which may limit the utility of multi-source orchestration.

Open questions / follow-ons

• How does RAMOSE perform under large-scale or highly concurrent workloads involving complex multi-source orchestration?
• Can the model-agnostic join approach be optimized or extended to support incremental data updates or streaming?
• How might finer-grained or dynamic authorization models be integrated for more secure write operations?
• What is the resilience of the orchestration pipeline against partial endpoint failures or network instability in practice?

Why it matters for bot defense

For bot-defense and CAPTCHA practitioners working in scholarly infrastructures or data-sharing platforms, RAMOSE offers a valuable middleware for implementing standards-compliant REST APIs that unite heterogeneous data sources transparently. Its declarative configuration reduces engineering effort, accelerating deployment of consistent interfaces essential for interoperability and reuse. The support for authentication on write operations aligns with security best practices, while caching and pagination help manage high query volumes and mitigate backend overloads. However, since RAMOSE focuses on middleware rather than direct bot-detection mechanisms, bot-defense specialists should view it as complementary infrastructure to layer CAPTCHA challenges or behavioral detection above. Understanding RAMOSE’s query orchestration and caching can aid in designing rate-limiting or anomaly detection strategies integrated at API endpoints. The framework’s ability to join RDF and non-RDF results enables richer data services that might otherwise be too costly to implement securely and efficiently.

Cite

@article{arxiv2607_11218,
  title={ Enhancing RAMOSE, a framework for implementing REST APIs and semantic-actionable outputs over data sources },
  author={ Arcangelo Massari and Sergei Slinkin and Ivan Heibi and Silvio Peroni },
  journal={arXiv preprint arXiv:2607.11218},
  year={ 2026 },
  url={https://arxiv.org/abs/2607.11218}
}

Read the full paper

• arXiv:2607.11218 (abstract)
• arXiv:2607.11218 (PDF)