Struct ClientConfig 

pub struct ClientConfig {
    pub api_key: Option<String>,
    pub rate_limit: Option<f64>,
    pub timeout: Duration,
    pub user_agent: Option<String>,
    pub base_url: Option<String>,
    pub email: Option<String>,
    pub tool: Option<String>,
    pub retry_config: RetryConfig,
    pub cache_config: Option<CacheConfig>,
}

Configuration options for PubMed and PMC clients

This configuration allows customization of rate limiting, API keys, timeouts, and other client behavior to comply with NCBI guidelines and optimize performance.

Fields

api_key: Option<String>

NCBI E-utilities API key for increased rate limits

With an API key:

• Rate limit increases from 3 to 10 requests per second
• Better stability and reduced chance of blocking
• Required for high-volume applications

Get your API key at: https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/

rate_limit: Option<f64>

Rate limit in requests per second

Default values:

• 3.0 without API key (NCBI guideline)
• 10.0 with API key (NCBI guideline)

Setting this value overrides the automatic selection based on API key presence.

timeout: Duration

HTTP request timeout

Default: 30 seconds

user_agent: Option<String>

Custom User-Agent string for HTTP requests

Default: “pubmed-client/{version}”

base_url: Option<String>

Base URL for NCBI E-utilities

Default: https://eutils.ncbi.nlm.nih.gov/entrez/eutils This should rarely need to be changed unless using a proxy or test environment.

email: Option<String>

Email address for identification (recommended by NCBI)

NCBI recommends including an email address in requests for contact in case of problems. This is automatically added to requests.

tool: Option<String>

Tool name for identification (recommended by NCBI)

NCBI recommends including a tool name in requests. Default: “pubmed-client”

retry_config: RetryConfig

Retry configuration for handling transient failures

Default: 3 retries with exponential backoff starting at 1 second

cache_config: Option<CacheConfig>

Cache configuration for response caching

Default: disabled (None). Use ClientConfig::with_cache, ClientConfig::with_redis_cache, or ClientConfig::with_sqlite_cache to enable caching.

Implementations

impl ClientConfig

pub fn new() -> Self

Create a new configuration with default settings

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new();

pub fn with_api_key<S: Into<String>>(self, api_key: S) -> Self

Set the NCBI API key

Arguments

• api_key - Your NCBI E-utilities API key

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_api_key("your_api_key_here");

pub fn with_rate_limit(self, rate: f64) -> Self

Set a custom rate limit

Arguments

• rate - Requests per second (must be positive)

Example

use pubmed_client::config::ClientConfig;

// Custom rate limit of 5 requests per second
let config = ClientConfig::new()
    .with_rate_limit(5.0);

pub fn with_timeout(self, timeout: Duration) -> Self

Set the HTTP request timeout

Arguments

• timeout - Maximum time to wait for HTTP responses

Example

use pubmed_client::config::ClientConfig;
use pubmed_client::time::Duration;

let config = ClientConfig::new()
    .with_timeout(Duration::from_secs(60));

pub fn with_timeout_seconds(self, timeout_seconds: u64) -> Self

Set the HTTP request timeout in seconds (convenience method)

Arguments

• timeout_seconds - Maximum time to wait for HTTP responses in seconds

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_timeout_seconds(60);

pub fn with_user_agent<S: Into<String>>(self, user_agent: S) -> Self

Set a custom User-Agent string

Arguments

• user_agent - Custom User-Agent for HTTP requests

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_user_agent("MyApp/1.0");

pub fn with_base_url<S: Into<String>>(self, base_url: S) -> Self

Set a custom base URL for NCBI E-utilities

Arguments

• base_url - Base URL for E-utilities API

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_base_url("https://proxy.example.com/eutils");

pub fn with_email<S: Into<String>>(self, email: S) -> Self

Set email address for NCBI identification

Arguments

• email - Your email address for NCBI contact

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_email("researcher@university.edu");

pub fn with_tool<S: Into<String>>(self, tool: S) -> Self

Set tool name for NCBI identification

Arguments

• tool - Your application/tool name

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_tool("BioinformaticsApp");

pub fn with_retry_config(self, retry_config: RetryConfig) -> Self

Set retry configuration for handling transient failures

Arguments

• retry_config - Custom retry configuration

Example

use pubmed_client::config::ClientConfig;
use pubmed_client::retry::RetryConfig;
use pubmed_client::time::Duration;

let retry_config = RetryConfig::new()
    .with_max_retries(5)
    .with_initial_delay(Duration::from_secs(2));

let config = ClientConfig::new()
    .with_retry_config(retry_config);

pub fn with_cache(self) -> Self

Enable caching with default configuration

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_cache();

pub fn with_cache_config(self, cache_config: CacheConfig) -> Self

Set cache configuration

Arguments

• cache_config - Custom cache configuration

Example

use pubmed_client::config::ClientConfig;
use pubmed_client::cache::CacheConfig;

let cache_config = CacheConfig {
    max_capacity: 5000,
    ..Default::default()
};

let config = ClientConfig::new()
    .with_cache_config(cache_config);

pub fn without_cache(self) -> Self

Disable all caching

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .without_cache();

pub fn with_redis_cache(self, url: impl Into<String>) -> Self

Enable Redis-backed caching.

Requires the cache-redis feature. The cache uses JSON serialisation with per-entry TTL (default: 7 days from CacheConfig::default).

Arguments

• url - Redis connection URL, e.g. "redis://127.0.0.1/"

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_redis_cache("redis://127.0.0.1/");

pub fn with_sqlite_cache(self, path: impl Into<PathBuf>) -> Self

Enable SQLite-backed caching.

Requires the cache-sqlite feature. Not available on WASM targets. The database file is created automatically if it does not exist.

Arguments

• path - Path to the SQLite database file

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new()
    .with_sqlite_cache("/tmp/pubmed_cache.db");

pub fn effective_rate_limit(&self) -> f64

Get the effective rate limit based on configuration

Returns the configured rate limit, or the appropriate default based on whether an API key is present.

Returns

• Custom rate limit if set
• 10.0 requests/second if API key is present
• 3.0 requests/second if no API key

pub fn create_rate_limiter(&self) -> RateLimiter

Create a rate limiter based on this configuration

Returns

A RateLimiter configured with the appropriate rate limit

Example

use pubmed_client::config::ClientConfig;

let config = ClientConfig::new().with_api_key("your_key");
let rate_limiter = config.create_rate_limiter();

pub fn effective_base_url(&self) -> &str

Get the base URL for E-utilities

Returns the configured base URL or the default NCBI E-utilities URL.

pub fn effective_user_agent(&self) -> String

Get the User-Agent string

Returns the configured User-Agent or a default based on the crate name and version.

pub fn effective_tool(&self) -> &str

Get the tool name for NCBI identification

Returns the configured tool name or the default.

pub fn build_api_params(&self) -> Vec<(String, String)>

Build query parameters for NCBI API requests

This includes API key, email, and tool parameters when configured.

Trait Implementations

impl Clone for ClientConfig

fn clone(&self) -> ClientConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for ClientConfig

fn default() -> Self

Returns the “default value” for a type.