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§
- Ga4gh
Beacon Query - The POST body for
Client::post_ga4gh_beacon_query. - Ga4gh
Callset Query - The POST body for
Client::search_ga4gh_callset. - Ga4gh
Features Query - The POST body for
Client::search_ga4gh_features. - Ga4gh
Featuresets Query - The POST body for
Client::search_ga4gh_featuresets. - Ga4gh
References Query - The POST body for
Client::search_ga4gh_references. - Ga4gh
Referencesets Query - The POST body for
Client::search_ga4gh_referencesets. - Ga4gh
Variant Annotations Query - The POST body for
Client::search_ga4gh_variant_annotations. - Ga4gh
Variant Annotationsets Query - The POST body for
Client::search_ga4gh_variant_annotationsets. - Ga4gh
Variants Query - The POST body for
Client::search_ga4gh_variants. - Ga4gh
Variantsets Query - 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-versioninCargo.toml. - VERSION
- The current version of this crate.
Functions§
- default_
user_ agent - Returns the default
User-Agentheader value.