<!--
SPDX-FileCopyrightText: 2026 Arcangelo Massari <arcangelo.massari@unibo.it>

SPDX-License-Identifier: CC-BY-4.0
-->

# Quick start

RAMOSE turns SPARQL endpoints into documented REST APIs. You write a spec file describing your queries, and RAMOSE handles routing, type casting, filtering, and documentation generation.

## Install

```sh
pip install ramose
```

Requires Python 3.10 or later.

To use the [SPARQL Anything](https://sparql-anything.cc/) engine, install the optional extra:

```sh
pip install ramose[sparql-anything]
```

## Create a spec file

Save this as `meta_v1.hf`. RAMOSE also accepts the same spec as `.yaml` or `.yml`; see the spec reference for the
YAML mirror syntax.

```
#url /v1
#type api
#base https://api.opencitations.net/meta
#title OpenCitations Meta REST API
#description REST API for bibliographic metadata from OpenCitations Meta
#version 1.0.0
#license ISC
#contacts [contact@opencitations.net](mailto:contact@opencitations.net)
#endpoint https://opencitations.net/meta/sparql
#method post

#url /metadata/{doi}
#type operation
#doi str(10\..+)
#method get
#description Returns bibliographic metadata for the given DOI.
#call /metadata/10.1162/qss_a_00292
#field_type str(title) datetime(pub_date) str(venue) str(type)
#sparql PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
PREFIX datacite: <http://purl.org/spar/datacite/>
PREFIX dcterm: <http://purl.org/dc/terms/>
PREFIX fabio: <http://purl.org/spar/fabio/>
PREFIX frbr: <http://purl.org/vocab/frbr/core#>
PREFIX literal: <http://www.essepuntato.it/2010/06/literalreification/>
PREFIX prism: <http://prismstandard.org/namespaces/basic/2.0/>
SELECT ?title ?pub_date ?venue ?type WHERE {
  ?identifier literal:hasLiteralValue "[[doi]]"^^xsd:string ;
    datacite:usesIdentifierScheme datacite:doi ;
    ^datacite:hasIdentifier ?res .
  OPTIONAL { ?res dcterm:title ?title }
  OPTIONAL { ?res prism:publicationDate ?pub_date }
  OPTIONAL {
    ?res frbr:partOf+ ?journal .
    ?journal a fabio:Journal ; dcterm:title ?venue
  }
  OPTIONAL { ?res a ?type . FILTER(?type != fabio:Expression) }
}
```

The first section declares the API (endpoint, metadata). The second defines an operation: a URL pattern with a `{doi}` parameter, mapped to a SPARQL query where `[[doi]]` gets replaced at runtime.

## Run locally

```sh
python -m ramose -s meta_v1.hf -c '/v1/metadata/10.1162/qss_a_00292'
```

Output:

```
# Response HTTP code: 200
# Body:
[{"title": "OpenCitations Meta", "pub_date": "2024", "venue": "Quantitative Science Studies", "type": "journal article"}]
# Content-type: application/json
```

## Start the web server

```sh
python -m ramose -s meta_v1.hf -w 127.0.0.1:8080
```

Open `http://localhost:8080/v1` for auto-generated documentation, or query `http://localhost:8080/v1/metadata/10.1162/qss_a_00292` directly.

## What's next

- [Spec file format](01-spec-file.md) for HF and YAML source files
- [CLI](02-cli.md) for all command-line options
- [Python API](03-python-api.md) for programmatic usage
- [Query parameters](04-parameters.md) for filtering and sorting results