aspero_datacite/
lib.rs

1//! DataCite provider.
2//!
3//! DataCite registers DOIs for arXiv, Zenodo, Figshare, Dryad and most
4//! research data and software. Its REST API (JSON:API) gives lookups,
5//! batched lookups, and keyword search with year and type filters; records
6//! carry abstracts (as "Abstract" descriptions) and stated arXiv IDs. Free;
7//! about 3,000 requests per 5 minutes.
8//!
9//! Observed 2026-11-10: **relevance ranking only works with page-number
10//! paging** (`sort=relevance&page[number]=N`); with cursor paging results
11//! come back by creation date regardless. So the provider's [`Cursor`] is
12//! the next page number. Year ranges use the query syntax
13//! (`publicationYear:[2017 TO *]`); `published=` only takes year lists.
14
15mod wire;
16
17use std::sync::Arc;
18use std::time::Duration;
19
20use aspero_core::http::{escape_lucene, path_segment};
21use aspero_core::{
22    Capabilities, Cursor, Doi, Error, FieldSet, Filter, Hit, HttpClient, HttpRequest, HttpResponse,
23    IdKind, Lookup, Page, Provider, ProviderId, ResiliencePolicy, Response, Result, SearchMode,
24    SearchQuery, SourceRecord, WorkId,
25};
26use async_trait::async_trait;
27
28use crate::wire::WireList;
29
30pub const ID: ProviderId = ProviderId::from_static("datacite");
31
32pub const DEFAULT_BASE_URL: &str = "https://api.datacite.org";
33
34pub(crate) const ARXIV_DOI_PREFIX: &str = "10.48550";
35
36/// DOIs per batched `query=doi:(…)` lookup.
37const MAX_BATCH: usize = 50;
38
39/// DataCite's page-size cap.
40const MAX_PAGE: u32 = 1000;
41
42/// Extra parameters passed through to DataCite's search filters.
43const PASSTHROUGH: &[&str] = &["client-id", "prefix", "affiliation-id", "has-citations"];
44
45#[derive(Debug, Clone)]
46#[non_exhaustive]
47pub struct DataciteConfig {
48    pub base_url: String,
49}
50
51impl Default for DataciteConfig {
52    fn default() -> Self {
53        DataciteConfig {
54            base_url: DEFAULT_BASE_URL.to_owned(),
55        }
56    }
57}
58
59pub struct Datacite {
60    config: DataciteConfig,
61    http: Arc<dyn HttpClient>,
62    capabilities: Capabilities,
63}
64
65impl Datacite {
66    pub fn new(config: DataciteConfig, http: Arc<dyn HttpClient>) -> Self {
67        let mut capabilities = Capabilities::default();
68        capabilities.lookup_kinds = vec![IdKind::Doi, IdKind::Arxiv];
69        capabilities.max_batch = MAX_BATCH;
70        capabilities.fields = FieldSet::ALL;
71        capabilities.search = true;
72        capabilities.search_filters = vec![Filter::Years, Filter::WorkType];
73        Datacite {
74            config,
75            http,
76            capabilities,
77        }
78    }
79
80    /// About 10 req/s allowed; stay well under.
81    pub fn default_policy() -> ResiliencePolicy {
82        let mut policy = ResiliencePolicy::default();
83        policy.min_interval = Duration::from_millis(200);
84        policy
85    }
86
87    fn url(&self, rest: &str, params: &[(&str, String)]) -> Result<String> {
88        let base = format!("{}/dois{rest}", self.config.base_url.trim_end_matches('/'));
89        let url = if params.is_empty() {
90            url::Url::parse(&base)
91        } else {
92            url::Url::parse_with_params(&base, params)
93        };
94        url.map(String::from)
95            .map_err(|e| Error::BadRequest(format!("invalid DataCite base URL: {e}")))
96    }
97
98    async fn get(&self, url: String) -> Result<HttpResponse> {
99        let req = HttpRequest::get(url).header("accept", "application/vnd.api+json");
100        let resp = self.http.send(req).await?;
101        check(&resp)?;
102        Ok(resp)
103    }
104
105    async fn lookup_one(&self, doi: &Doi) -> Result<Option<SourceRecord>> {
106        let resp = match self
107            .get(self.url(&format!("/{}", path_segment(doi.as_str())), &[])?)
108            .await
109        {
110            Ok(resp) => resp,
111            Err(Error::NotFound) => return Ok(None),
112            Err(e) => return Err(e),
113        };
114        let body: serde_json::Value = serde_json::from_slice(&resp.body).map_err(Error::decode)?;
115        let data = body.get("data").ok_or_else(|| Error::decode(MissingData))?;
116        wire::to_record(data, resp.received_at)
117            .map(Some)
118            .map_err(Error::decode)
119    }
120
121    async fn list(&self, params: &[(&str, String)]) -> Result<(Vec<Hit>, wire::WireMeta)> {
122        let resp = self.get(self.url("", params)?).await?;
123        let list: WireList = serde_json::from_slice(&resp.body).map_err(Error::decode)?;
124        let hits = list
125            .data
126            .iter()
127            .map(|v| wire::to_record(v, resp.received_at).map(|r| Hit::new(r, None)))
128            .collect::<serde_json::Result<_>>()
129            .map_err(Error::decode)?;
130        Ok((hits, list.meta))
131    }
132}
133
134#[derive(Debug, thiserror::Error)]
135#[error("DataCite response has no `data`")]
136struct MissingData;
137
138fn to_doi(id: &WorkId) -> Result<Doi> {
139    match id {
140        WorkId::Doi(doi) => Ok(doi.clone()),
141        WorkId::Arxiv(arxiv) => Ok(format!("{ARXIV_DOI_PREFIX}/arxiv.{}", arxiv.id()).parse()?),
142        _ => Err(Error::Unsupported("DataCite lookup of non-DOI identifiers")),
143    }
144}
145
146fn check(resp: &HttpResponse) -> Result<()> {
147    if resp.is_success() {
148        return Ok(());
149    }
150    let message = message(resp);
151    Err(match resp.status {
152        400 | 422 => Error::BadRequest(message.unwrap_or_else(|| "rejected by DataCite".into())),
153        401 | 403 => Error::AuthRejected { message },
154        404 => Error::NotFound,
155        429 => Error::RateLimited {
156            retry_after: resp
157                .header("retry-after")
158                .and_then(|v| v.trim().parse().ok())
159                .map(Duration::from_secs),
160        },
161        status => Error::Server { status, message },
162    })
163}
164
165/// The `title` of a JSON:API `errors` value, which DataCite sends as an
166/// object or an array.
167fn message(resp: &HttpResponse) -> Option<String> {
168    let json: serde_json::Value = serde_json::from_slice(&resp.body).ok()?;
169    let errors = json.get("errors")?;
170    let first = errors.as_array().and_then(|a| a.first()).unwrap_or(errors);
171    first.get("title")?.as_str().map(str::to_owned)
172}
173
174#[async_trait]
175impl Provider for Datacite {
176    fn id(&self) -> ProviderId {
177        ID
178    }
179
180    fn capabilities(&self) -> &Capabilities {
181        &self.capabilities
182    }
183
184    async fn lookup(&self, ids: &[WorkId], _fields: FieldSet) -> Result<Response<Vec<Lookup>>> {
185        let dois = ids.iter().map(to_doi).collect::<Result<Vec<_>>>()?;
186        if let [doi] = dois.as_slice() {
187            let record = self.lookup_one(doi).await?;
188            return Ok(Response::new(vec![Lookup {
189                id: ids[0].clone(),
190                record,
191            }]));
192        }
193        let mut found = Vec::new();
194        for chunk in dois.chunks(MAX_BATCH) {
195            let terms: Vec<String> = chunk
196                .iter()
197                .map(|d| format!("\"{}\"", d.as_str().replace('"', "\\\"")))
198                .collect();
199            let params = [
200                ("query", format!("doi:({})", terms.join(" OR "))),
201                ("page[size]", chunk.len().to_string()),
202            ];
203            let (hits, _) = self.list(&params).await?;
204            found.extend(hits.into_iter().map(|h| h.record));
205        }
206        let lookups = ids
207            .iter()
208            .zip(&dois)
209            .map(|(id, doi)| Lookup {
210                id: id.clone(),
211                record: found
212                    .iter()
213                    .find(|r| {
214                        r.ids
215                            .iter()
216                            .any(|i| matches!(i, WorkId::Doi(d) if d == doi))
217                    })
218                    .cloned(),
219            })
220            .collect();
221        Ok(Response::new(lookups))
222    }
223
224    async fn search(&self, query: &SearchQuery) -> Result<Response<Page>> {
225        if query.mode != SearchMode::Keywords {
226            return Err(Error::Unsupported("DataCite has no citation matcher"));
227        }
228        let mut clauses = Vec::new();
229        if !query.text.trim().is_empty() {
230            clauses.push(format!("({})", escape_lucene(query.text.trim())));
231        }
232        if let Some(years) = query.years {
233            let end = |y: Option<i16>| y.map_or("*".to_owned(), |y| y.to_string());
234            clauses.push(format!(
235                "publicationYear:[{} TO {}]",
236                end(years.from),
237                end(years.to)
238            ));
239        }
240        let mut params: Vec<(&str, String)> = Vec::new();
241        for (key, value) in &query.extra {
242            match key.as_str() {
243                // Raw query syntax, ANDed with the rest.
244                "query" => clauses.push(format!("({value})")),
245                k if PASSTHROUGH.contains(&k) => params.push((k, value.clone())),
246                other => {
247                    return Err(Error::BadRequest(format!(
248                        "unknown DataCite parameter {other:?} (supported: query, {})",
249                        PASSTHROUGH.join(", ")
250                    )));
251                }
252            }
253        }
254        if !clauses.is_empty() {
255            params.insert(0, ("query", clauses.join(" AND ")));
256        }
257        if let Some(t) = &query.work_type {
258            let id = wire::resource_type_id(t).ok_or_else(|| {
259                Error::BadRequest(format!(
260                    "DataCite has no resource type matching {:?}",
261                    t.as_csl()
262                ))
263            })?;
264            params.push(("resource-type-id", id.to_owned()));
265        }
266        let page_number: u32 = match &query.page.cursor {
267            None => 1,
268            Some(c) => {
269                c.0.parse()
270                    .map_err(|_| Error::BadRequest(format!("invalid DataCite cursor {:?}", c.0)))?
271            }
272        };
273        params.push(("sort", "relevance".into()));
274        params.push(("page[number]", page_number.to_string()));
275        params.push((
276            "page[size]",
277            query.page.limit.clamp(1, MAX_PAGE).to_string(),
278        ));
279
280        let (hits, meta) = self.list(&params).await?;
281        let more = meta.total_pages.is_some_and(|pages| page_number < pages) && !hits.is_empty();
282        let next = more.then(|| Cursor((page_number + 1).to_string()));
283        Ok(Response::new(Page::new(hits, meta.total, next)))
284    }
285}
aspero_datacite/lib.rs

aspero_datacite/
lib.rs
