refget-rs

A Rust implementation of the GA4GH refget API, covering both the Sequences v2.0.0 and Sequence Collections v1.0.0 specifications.

Visit us at Fulcrum Genomics to learn more about how we can power your Bioinformatics with refget-rs and beyond.

Overview

refget-rs provides:

• refget-digest — SHA-512/24 (sha512t24u) and RFC 8785 JSON Canonicalization (JCS) computation
• refget-model — Domain types for sequences and sequence collections, including the comparison algorithm
• refget-store — Storage traits with in-memory and indexed-FASTA backends
• refget-server — Composable Axum router library for all refget endpoints
• refget-server-bin — Standalone server binary that serves FASTA files via the refget API
• refget-tools — CLI tool for computing refget digests from FASTA files

Installation

Building from source

Clone the repository:

git clone https://github.com/fg-labs/refget-rs

Build the release binaries:

cd refget-rs
cargo build --release

The two binaries will be at target/release/refget-server and target/release/refget-tools.

Usage

Serving FASTA files

Start a refget server that serves one or more indexed FASTA files:

refget-server --fasta ref.fa --port 8080

You can pass multiple files or a directory:

refget-server --fasta /path/to/fastas/ --port 8080

Note: Each FASTA file must have a companion .fai index (e.g. ref.fa.fai).

API Endpoints

Sequences v2.0.0

Endpoint	Description
GET /sequence/service-info	Service info (algorithms, formats)
GET /sequence/{digest}	Retrieve sequence bases (supports Range header, start/end query params)
GET /sequence/{digest}/metadata	Sequence metadata (MD5, sha512t24u, length, aliases)

Sequence Collections v1.0.0

Endpoint	Description
GET /service-info	Service info with collection schema
GET /collection/{digest}?level=0|1|2	Collection at specified level (default: 2)
GET /comparison/{digest1}/{digest2}	Compare two collections
POST /comparison/{digest1}	Compare a collection against POSTed Level 2 JSON
GET /list/collection	Paginated collection listing with attribute filters
GET /attribute/collection/{attr}/{digest}	Single attribute array by digest

Computing digests

Compute per-sequence digests from a FASTA file:

refget-tools digest-fasta ref.fa

Output (TSV): name, length, md5, sha512t24u

Compute sequence collection digests:

refget-tools digest-collection ref.fa

Resources

• GA4GH refget specification
• Sequence Collections specification
• Issues: Report a bug or request a feature
• Pull requests: Submit a patch or new feature
• Contributors guide
• License: Released under the MIT license

Authors

• Nils Homer

Sponsors

Development of refget-rs is supported by Fulcrum Genomics.

Become a sponsor

Disclaimer

This software is under active development. While we make a best effort to test this software and to fix issues as they are reported, this software is provided as-is without any warranty (see the license for details). Please submit an issue, and better yet a pull request as well, if you discover a bug or identify a missing feature. Please contact Fulcrum Genomics if you are considering using this software or are interested in sponsoring its development.