Skip to main content

Crate ensemblrest

Crate ensemblrest 

Source
Expand description

A Rust client library for the Ensembl REST API.

This crate is a port of goensemblrest, itself a port of pyEnsemblRest, and covers all 106 endpoints.

§Quickstart

use ensemblrest::types::LookupRecord;
use ensemblrest::Client;

let client = Client::new()?;
let braf: LookupRecord = client.get_lookup_by_id("ENSG00000157764", &[])?.json()?;
println!("{} is a {}", braf.display_name, braf.biotype);

§Decoding responses

Every endpoint method returns a Response. Decode it with Response::json for JSON, or Response::text for the formats Ensembl serves as text.

use ensemblrest::options::content_type;
use ensemblrest::Client;

let client = Client::new()?;
let fasta = client
    .get_sequence_by_id("ENSG00000157764", &[content_type("text/x-fasta")])?
    .text()?;

json accepts any serde::Deserialize type, so endpoints without a model in types still work via serde_json::Value.

§GA4GH query structs

The GA4GH search endpoints take a body of optional filters, most of them the same type as their neighbours. Each such endpoint therefore takes a named Ga4gh*Query struct rather than a row of positional Options, so a transposed pair cannot compile into a silently wrong query. Fields left None are omitted from the request body.

use ensemblrest::{Client, Ga4ghReferencesQuery};

let client = Client::new()?;
let references = client.search_ga4gh_references(
    &Ga4ghReferencesQuery {
        reference_set_id: Some("GRCh38"),
        accession: Some("GCA_000001405"),
        page_size: Some(10),
        ..Default::default()
    },
    &[],
)?;

§Configuration

use ensemblrest::Client;
use std::time::Duration;

let client = Client::builder()
    .timeout(Duration::from_secs(30))
    .rate_limit(15, Duration::from_secs(1))
    .max_attempts(5)
    .user_agent("my-tool/1.0")
    .build()?;

Client is cheap to clone and shares one rate limiter and connection pool across clones, so a cloned client observes one global rate limit.

§Errors

use ensemblrest::{ApiErrorKind, Client};

let client = Client::new()?;
match client.get_lookup_by_id("NOT_A_REAL_ID", &[]) {
    Ok(response) => println!("{}", response.status()),
    Err(e) if e.is_not_found() => println!("no such identifier"),
    Err(e) if e.api_kind() == Some(ApiErrorKind::RateLimit) => println!("rate limited"),
    Err(e) => println!("failed: {e}"),
}

Re-exports§

pub use ratelimit::RateLimitInfo;
pub use error::ApiError;
pub use error::ApiErrorKind;
pub use error::Error;
pub use error::Result;
pub use response::Response;
pub use options::RequestOption;
pub use options::content_type;
pub use options::header;
pub use options::query;
pub use client::Client;
pub use client::ClientBuilder;
pub use serde_json;

Modules§

client
The Ensembl REST API client and its builder.
endpoints
The catalog of Ensembl REST API endpoints and dynamic dispatch.
error
Error types for the Ensembl REST API client.
options
Per-call request customization.
ratelimit
Client-side sliding-window rate limiting and rate-limit telemetry.
response
The response handle returned by every endpoint method.
types
Deserialization models for common Ensembl REST API responses.

Structs§

Ga4ghBeaconQuery
The POST body for Client::post_ga4gh_beacon_query.
Ga4ghCallsetQuery
The POST body for Client::search_ga4gh_callset.
Ga4ghFeaturesQuery
The POST body for Client::search_ga4gh_features.
Ga4ghFeaturesetsQuery
The POST body for Client::search_ga4gh_featuresets.
Ga4ghReferencesQuery
The POST body for Client::search_ga4gh_references.
Ga4ghReferencesetsQuery
The POST body for Client::search_ga4gh_referencesets.
Ga4ghVariantAnnotationsQuery
The POST body for Client::search_ga4gh_variant_annotations.
Ga4ghVariantAnnotationsetsQuery
The POST body for Client::search_ga4gh_variant_annotationsets.
Ga4ghVariantsQuery
The POST body for Client::search_ga4gh_variants.
Ga4ghVariantsetsQuery
The POST body for Client::search_ga4gh_variantsets.

Constants§

DEFAULT_BASE_URL
The official Ensembl REST API endpoint.
DEFAULT_CONTENT_TYPE
The default MIME type used for requests and responses.
DEFAULT_MAX_ATTEMPTS
The default maximum number of attempts for a single call.
DEFAULT_MAX_RESPONSE_BYTES
The default cap on a single response body, in bytes (100 MiB).
DEFAULT_REQS_PER_SEC
The default number of requests permitted per rate-limit window.
DEFAULT_TIMEOUT
The default per-request timeout.
DEFAULT_WALL_TIME
The default rate-limit sliding-window duration.
MSRV
The crate’s minimum supported Rust version, from rust-version in Cargo.toml.
VERSION
The current version of this crate.

Functions§

default_user_agent
Returns the default User-Agent header value.