#![deny(missing_docs)]
mod date;
mod error;
mod id;
mod index;
mod limit;
mod meta;
pub use crate::date::{DateParseError, PartialDate, Timespan, TimespanParseError};
pub use crate::error::{Error, Result};
pub use crate::id::{Identifier, Oci};
pub use crate::index::{Citation, Comparison, Field, Filter, Order, Refine, Sort};
pub use crate::limit::RateLimit;
pub use crate::meta::{Entity, Metadata};
use crate::index::Count;
use crate::limit::{Limiter, retry_after};
use percent_encoding::{AsciiSet, CONTROLS, utf8_percent_encode};
use reqwest::{Client, StatusCode};
use serde::de::DeserializeOwned;
use std::sync::Arc;
use std::time::Duration;
const IN_PATH: &AsciiSet = &CONTROLS
.add(b' ')
.add(b'"')
.add(b'<')
.add(b'>')
.add(b'?')
.add(b'#')
.add(b'%')
.add(b'`')
.add(b'{')
.add(b'}')
.add(b'\\')
.add(b'^')
.add(b'|');
#[derive(Debug, Clone)]
pub struct OpenCitations {
base_url: String,
client: Client,
limiter: Arc<Limiter>,
max_retries: u32,
}
impl OpenCitations {
const BASE_URL: &'static str = "https://api.opencitations.net";
const INDEX: &'static str = "index/v2";
const META: &'static str = "meta/v1";
pub const META_BATCH: usize = 10;
pub fn builder() -> OpenCitationsBuilder {
OpenCitationsBuilder::new()
}
pub fn base_url(&self) -> &str {
&self.base_url
}
pub fn rate_limit(&self) -> RateLimit {
self.limiter.rate()
}
pub async fn citations(&self, id: &Identifier) -> Result<Vec<Citation>> {
self.citations_where(id, &Refine::new()).await
}
pub async fn citations_where(&self, id: &Identifier, refine: &Refine) -> Result<Vec<Citation>> {
self.get(
&format!("{}/citations/{}", Self::INDEX, encode(id)),
&refine.params(),
"citations",
)
.await
}
pub async fn references(&self, id: &Identifier) -> Result<Vec<Citation>> {
self.references_where(id, &Refine::new()).await
}
pub async fn references_where(
&self,
id: &Identifier,
refine: &Refine,
) -> Result<Vec<Citation>> {
self.get(
&format!("{}/references/{}", Self::INDEX, encode(id)),
&refine.params(),
"references",
)
.await
}
pub async fn citation(&self, oci: &Oci) -> Result<Option<Citation>> {
let found: Vec<Citation> = self
.get(
&format!("{}/citation/{oci}", Self::INDEX),
&[],
"the citation",
)
.await?;
Ok(found.into_iter().next())
}
pub async fn citation_count(&self, id: &Identifier) -> Result<u64> {
self.count(&format!("{}/citation-count/{}", Self::INDEX, encode(id)))
.await
}
pub async fn reference_count(&self, id: &Identifier) -> Result<u64> {
self.count(&format!("{}/reference-count/{}", Self::INDEX, encode(id)))
.await
}
pub async fn venue_citation_count(&self, issn: &Identifier) -> Result<u64> {
self.count(&format!(
"{}/venue-citation-count/{}",
Self::INDEX,
encode(issn)
))
.await
}
pub async fn metadata(&self, ids: &[Identifier]) -> Result<Vec<Metadata>> {
let mut records = Vec::with_capacity(ids.len());
for batch in ids.chunks(Self::META_BATCH) {
let joined = batch.iter().map(encode).collect::<Vec<_>>().join("__");
let found: Vec<Metadata> = self
.get(
&format!("{}/metadata/{joined}", Self::META),
&[],
"the metadata",
)
.await?;
records.extend(found);
}
Ok(records)
}
async fn count(&self, route: &str) -> Result<u64> {
let counts: Vec<Count> = self.get(route, &[], "the count").await?;
let Some(count) = counts.first() else {
return Ok(0);
};
count.count.trim().parse().map_err(|_| Error::Api {
status: 200,
body: format!("`{}` is not a count", count.count),
})
}
async fn get<T: DeserializeOwned>(
&self,
route: &str,
params: &[(&'static str, String)],
what: &'static str,
) -> Result<T> {
let url = format!("{}/{route}", self.base_url);
for attempt in 1.. {
self.limiter.acquire().await;
tracing::debug!(%url, attempt, "requesting");
let response = self.client.get(&url).query(params).send().await?;
let status = response.status();
if status == StatusCode::TOO_MANY_REQUESTS {
if attempt > self.max_retries {
return Err(Error::RateLimited { attempts: attempt });
}
let delay = retry_after(response.headers())
.unwrap_or_else(|| Duration::from_secs(u64::from(attempt)));
self.limiter.back_off(delay);
continue;
}
let body = response.text().await?;
if !status.is_success() {
let body = body.trim().to_string();
return Err(if status == StatusCode::NOT_FOUND {
Error::NoSuchOperation { message: body }
} else {
Error::Api {
status: status.as_u16(),
body,
}
});
}
return serde_json::from_str(&body).map_err(|source| Error::Malformed { what, source });
}
unreachable!("the retry loop returns or continues")
}
}
fn encode(id: &Identifier) -> String {
utf8_percent_encode(&id.to_string(), IN_PATH).to_string()
}
#[derive(Debug, Default)]
pub struct OpenCitationsBuilder {
user_agent: Option<String>,
token: Option<String>,
base_url: Option<String>,
rate_limit: Option<RateLimit>,
max_retries: Option<u32>,
}
impl OpenCitationsBuilder {
const DEFAULT_MAX_RETRIES: u32 = 3;
pub fn new() -> Self {
Self::default()
}
pub fn token<'a>(mut self, token: impl Into<Option<&'a str>>) -> Self {
self.token = token.into().map(str::to_owned);
self
}
pub fn user_agent<'a>(mut self, user_agent: impl Into<Option<&'a str>>) -> Self {
self.user_agent = user_agent.into().map(str::to_owned);
self
}
pub fn base_url<'a>(mut self, base_url: impl Into<Option<&'a str>>) -> Self {
self.base_url = base_url.into().map(str::to_owned);
self
}
pub fn rate_limit(mut self, rate_limit: impl Into<Option<RateLimit>>) -> Self {
self.rate_limit = rate_limit.into();
self
}
pub fn max_retries(mut self, max_retries: impl Into<Option<u32>>) -> Self {
self.max_retries = max_retries.into();
self
}
pub fn build(self) -> Result<OpenCitations> {
use reqwest::header;
let mut headers = header::HeaderMap::new();
let agent = self.user_agent.unwrap_or_else(|| {
format!(
"{}/{} ({})",
env!("CARGO_PKG_NAME"),
env!("CARGO_PKG_VERSION"),
env!("CARGO_PKG_REPOSITORY")
)
});
headers.insert(
header::USER_AGENT,
header::HeaderValue::from_str(&agent).map_err(|_| Error::Config {
msg: format!("failed to create User-Agent header for `{agent}`"),
})?,
);
if let Some(token) = &self.token {
headers.insert(
header::AUTHORIZATION,
header::HeaderValue::from_str(token).map_err(|_| Error::Config {
msg: "failed to create authorization header for the access token".to_string(),
})?,
);
}
let client = Client::builder()
.default_headers(headers)
.build()
.map_err(|_| Error::Config {
msg: "failed to initialize TLS backend".to_string(),
})?;
Ok(OpenCitations {
base_url: self
.base_url
.unwrap_or_else(|| OpenCitations::BASE_URL.to_string()),
client,
limiter: Arc::new(Limiter::new(self.rate_limit.unwrap_or_default())),
max_retries: self.max_retries.unwrap_or(Self::DEFAULT_MAX_RETRIES),
})
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_default_client_talks_to_opencitations_at_the_documented_rate() {
let client = OpenCitations::builder().build().unwrap();
assert_eq!(client.base_url(), "https://api.opencitations.net");
assert_eq!(client.rate_limit(), RateLimit::DOCUMENTED);
}
#[test]
fn an_identifier_is_encoded_only_where_it_has_to_be() {
assert_eq!(
encode(&Identifier::doi("10.1016/j.marpol.2021.104855")),
"doi:10.1016/j.marpol.2021.104855"
);
assert_eq!(
encode(&Identifier::doi("10.1000/a b?c#d")),
"doi:10.1000/a%20b%3Fc%23d"
);
}
#[tokio::test]
async fn asking_for_no_metadata_makes_no_request() {
let client = OpenCitations::builder()
.base_url("http://127.0.0.1:1")
.build()
.unwrap();
assert!(client.metadata(&[]).await.unwrap().is_empty());
}
}