crossref_client/lib.rs
1//! An async client for the [Crossref REST API](https://api.crossref.org/swagger-ui/index.html).
2//!
3//! `crossref-client` is a hard fork of [`crossref-rs`](https://github.com/MattsSe/crossref-rs)
4//! and has diverged substantially from it; changes are not upstreamed.
5//!
6//! The [`Crossref`] client provides methods matching the Crossref API routes:
7
8//! * `works` - `/works` route
9//! * `members` - `/members` route
10//! * `prefixes` - `/prefixes` route
11//! * `funders` - `/funders` route
12//! * `journals` - `/journals` route
13//! * `licenses` - `/licenses` route
14//! * `types` - `/types` route
15//! * `agency` - `/works/{doi}/agency` get DOI minting agency
16//!
17//! ## Usage
18
19//! ### Create a `Crossref` client:
20
21//! ```no_run
22//! # use crossref_client::Crossref;
23//! # async fn run() -> Result<(), crossref_client::Error> {
24//! let client = Crossref::builder().build()?;
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! If you have an [Authorization token for Crossref's Plus service](https://github.com/CrossRef/rest-api-doc#authorization-token-for-plus-service):
30//!
31//! ```no_run
32//! # use crossref_client::Crossref;
33//! # async fn run() -> Result<(), crossref_client::Error> {
34//! let client = Crossref::builder()
35//! .token("token")
36//! .build()?;
37//! # Ok(())
38//! # }
39//! ```
40//!
41//! Encouraged to use the **The Polite Pool**:
42//!
43//! [Good manners = more reliable service](https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service)
44//!
45//! To get into Crossref's polite pool include a email address
46//!
47//! ```no_run
48//! # use crossref_client::Crossref;
49//! # async fn run() -> Result<(), crossref_client::Error> {
50//! let client = Crossref::builder()
51//! .polite("polite@example.com")
52//! .token("your token")
53//! .build()?;
54//! # Ok(())
55//! # }
56//! ```
57//!
58//! ### Constructing Queries
59//! Not all components support queries and there are custom available parameters for each route that supports querying.
60//! For each resource components that supports querying there exist a Query struct: `WorksQuery`, `MembersQuery`, `FundersQuery`. The `WorksQuery` also differs from the others by supporting [deep paging with cursors](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors) and [field queries](https://github.com/CrossRef/rest-api-doc#works-field-queries).
61//!
62//! Otherwise creating queries works the same for all resource components:
63//!
64//! ```no_run
65//! # use crossref_client::*;
66//! # async fn run() -> crossref_client::Result<()> {
67//! let query = WorksQuery::new("Machine Learning")
68//! // field queries supported for `Works`
69//! .field_query(FieldQuery::author("Some Author"))
70//! // filters are specific for each resource component
71//! .filter(WorksFilter::HasOrcid)
72//! .order(Order::Asc)
73//! .sort(Sort::Score);
74//! # Ok(())
75//! # }
76//! ```
77//!
78//!
79//! ### Get Records
80//!
81//! See [this table](https://github.com/CrossRef/rest-api-doc#resource-components) for a detailed overview of the major components.
82//!
83//! There are 3 available targets:
84//!
85//! * **standalone resource components**: `/works`, `/members`, etc. that return a list list of the corresponding items and can be specified with queries
86//! * **Resource component with identifiers**: `/works/{doi}?<query>`,`/members/{member_id}?<query>`, etc. that returns a single item if found.
87//! * **combined with the `works` route**: The works component can be appended to other resources: `/members/{member_id}/works?<query>` etc. that returns a list of matching `Work` items.
88//!
89//! This resembles in the enums of the resource components, eg. for `Members`:
90//!
91//! ```no_run
92//! # use crossref_client::query::*;
93//! pub enum Members {
94//! /// target a specific member at `/members/{id}`
95//! Identifier(String),
96//! /// target all members that match the query at `/members?query...`
97//! Query(MembersQuery),
98//! /// target a `Work` for a specific member at `/members/{id}/works?query..`
99//! Works(WorksIdentQuery),
100//! }
101//! ```
102//!
103//! All options are supported by the client:
104//!
105//! **Single Item by DOI (ID)**
106//!
107//! Analogous methods exist for all resource components
108//!
109//! ```no_run
110//! # use crossref_client::*;
111//! # async fn run() -> crossref_client::Result<()> {
112//! # let client = Crossref::builder().build()?;
113//! let work = client.work("10.1037/0003-066X.59.1.29").await?;
114//!
115//! let agency = client.work_agency("10.1037/0003-066X.59.1.29").await?;
116//!
117//! let funder = client.funder("funder_id").await?;
118//!
119//! let member = client.member("member_id").await?;
120//! # Ok(())
121//! # }
122//! ```
123//!
124//! **Query**
125//!
126//! ```no_run
127//! # use crossref_client::*;
128//! # async fn run() -> crossref_client::Result<()> {
129//! # let client = Crossref::builder().build()?;
130//! let query = WorksQuery::new("Machine Learning");
131//!
132//! // one page of the matching results
133//! let works = client.works(query).await?;
134//! # Ok(())
135//! # }
136//! ```
137//!
138//! Alternatively insert a free form query term directly
139//!
140//! ```no_run
141//! # use crossref_client::*;
142//! # async fn run() -> crossref_client::Result<()> {
143//! # let client = Crossref::builder().build()?;
144//!
145//! // one page of the matching results
146//! let works = client.works("Machine Learning").await?;
147//! # Ok(())
148//! # }
149//! ```
150//!
151//! **Combining Routes with the `Works` route**
152//!
153//! For each resource component other than `Works` there exist methods to append a `WorksQuery` with the ID option `/members/{member_id}/works?<query>?`
154//!
155//! ```no_run
156//! # use crossref_client::*;
157//! # async fn run() -> crossref_client::Result<()> {
158//! # let client = Crossref::builder().build()?;
159//! let works = client.member_works( WorksQuery::new("machine learning")
160//! .sort(Sort::Score).into_ident("member_id")).await?;
161//! # Ok(())
162//! # }
163//! ```
164//!
165//! This would be the same as using the [`Crossref::works`] method by supplying the combined type
166//!
167//! ```no_run
168//! # use crossref_client::*;
169//! # async fn run() -> crossref_client::Result<()> {
170//! # let client = Crossref::builder().build()?;
171//! let works = client.works(WorksQuery::new("machine learning")
172//! .sort(Sort::Score)
173//! .into_combined_query::<Members>("member_id")).await?;
174//! # Ok(())
175//! # }
176//! ```
177//!
178//! ** Deep paging for `Works` **
179//! [Deep paging results](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors)
180//! Deep paging is supported for all queries, that return a list of `Work`, `WorkList`.
181//! This function returns a new iterator over pages of `Work`, which is returned as bulk of items as a `WorkList` by crossref.
182//! Usually a single page `WorkList` contains 20 items.
183//!
184//! # Example
185//!
186//! Iterate over all `Works` linked to search term `Machine Learning`
187//!
188//! ```no_run
189//! use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
190//! # async fn run() -> Result<(), crossref_client::Error> {
191//! let client = Crossref::builder().build()?;
192//!
193//! let mut pages = client.deep_page(WorksQuery::new("Machine Learning"));
194//! let mut all_works: Vec<Work> = Vec::new();
195//! while let Some(page) = pages.next().await {
196//! let page = page?;
197//! all_works.extend(page.items);
198//! }
199//!
200//! # Ok(())
201//! # }
202//! ```
203//!
204//! Which can be simplified to
205//!
206//! ```no_run
207//! use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
208//! # async fn run() -> Result<(), crossref_client::Error> {
209//! let client = Crossref::builder().build()?;
210//!
211//! let mut works = client.deep_page("Machine Learning").into_work_iter();
212//! let mut all_works: Vec<Work> = Vec::new();
213//! while let Some(work) = works.next().await {
214//! let work = work?;
215//! all_works.push(work);
216//! }
217//!
218//! # Ok(())
219//! # }
220//! ```
221//!
222//!
223//! # Example
224//!
225//! Iterate over all the pages (`WorkList`) of the funder with id `funder id` by using a combined query.
226//! A single `WorkList` usually holds 20 `Work` items.
227//!
228//! ```no_run
229//! use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
230//! # async fn run() -> Result<(), crossref_client::Error> {
231//! let client = Crossref::builder().build()?;
232//!
233//! let mut pages = client.deep_page(WorksQuery::default().into_combined_query::<Funders>("funder id"));
234//! let mut all_funder_work_list: Vec<WorkList> = Vec::new();
235//! while let Some(page) = pages.next().await {
236//! let page = page?;
237//! all_funder_work_list.push(page);
238//! }
239//!
240//! # Ok(())
241//! # }
242//! ```
243//! # Example
244//!
245//! Iterate over all `Work` items of a specfic funder directly.
246//!
247//! ```no_run
248//! use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
249//! # async fn run() -> Result<(), crossref_client::Error> {
250//! let client = Crossref::builder().build()?;
251//!
252//! let mut works = client.deep_page(WorksQuery::default()
253//! .into_combined_query::<Funders>("funder id"))
254//! .into_work_iter();
255//! let mut all_works: Vec<Work> = Vec::new();
256//! while let Some(work) = works.next().await {
257//! let work = work?;
258//! all_works.push(work);
259//! }
260//!
261//! # Ok(())
262//! # }
263//! ```
264
265#![warn(missing_docs)]
266
267mod error;
268/// client side rate limiting
269pub mod limit;
270/// provides types to construct a specific query
271pub mod query;
272/// provides the response types of the crossref api
273pub mod response;
274
275/// content negotiation
276pub mod cn;
277
278#[doc(inline)]
279pub use self::error::{Error, Result};
280
281#[doc(inline)]
282pub use self::limit::RateLimit;
283
284#[doc(inline)]
285pub use self::cn::CnFormat;
286
287#[doc(inline)]
288pub use self::query::works::{
289 FieldQuery, WorkElement, WorkListQuery, WorkResultControl, Works, WorksFilter, WorksIdentQuery,
290 WorksQuery,
291};
292
293pub use self::query::facet::{Facet, FacetCount};
294pub use self::query::funders::{Funders, FundersFilter, FundersQuery};
295pub use self::query::members::{Members, MembersFilter, MembersQuery};
296#[doc(inline)]
297pub use self::query::{Component, CrossrefQuery, CrossrefRoute, Order, ResultControl, Sort};
298pub use self::query::{
299 Journals, JournalsQuery, Licenses, LicensesQuery, Prefixes, Type, Types, Visibility,
300 WorksComponent,
301};
302pub use self::response::{
303 CrossrefType, Failure, Failures, Funder, FunderList, Journal, JournalList, LicenseCount,
304 LicenseList, Member, MemberList, MessageType, StyleList, TypeList, Work, WorkAgency, WorkList,
305};
306
307/// The types that appear in the public fields of a [`Work`], re-exported so a
308/// caller of [`Crossref::works`] can name them without reaching into
309/// [`response::work`].
310#[doc(inline)]
311pub use self::response::work::{
312 Affiliation, Agency, Assertion, AssertionGroup, ClinicalTrialNumber, ContentDomain,
313 Contributor, Date, DateField, DateParts, Explanation, FundingBody, ISSN, InstitutionId, Issue,
314 License, PartialDate, Reference, RelatedItems, Relation, Relations, ResourceLink, Review,
315 Update,
316};
317
318pub(crate) use self::response::{Message, Response};
319
320/// The async iterator trait implemented by [`WorkListIterator`].
321///
322/// Re-exported so callers can drive deep paging without depending on
323/// `async-iterator` directly.
324pub use async_iterator::Iterator as AsyncIterator;
325
326use crate::limit::{Limiter, retry_after};
327use crate::response::Prefix;
328use reqwest::{Client, StatusCode};
329use std::sync::Arc;
330
331/// Unwraps the payload a route is expected to answer with, or reports what
332/// crossref sent instead.
333macro_rules! get_item {
334 ($ident:ident, $response:expr) => {{
335 let response = $response;
336 match response.message {
337 Message::$ident(item) => Ok(item),
338 other => Err(Error::UnexpectedItem {
339 expected: MessageType::$ident,
340 got: other.message_type(),
341 }),
342 }
343 }};
344}
345
346macro_rules! impl_combined_works_query {
347 ($($name:ident $component:ident,)*) => {
348 $(
349 /// Return one page of the components's `Work` that match the query
350 ///
351 pub async fn $name(&self, ident: WorksIdentQuery) -> Result<WorkList> {
352 let resp = self.get_response(&$component::Works(ident)).await?;
353 get_item!(WorkList, resp)
354 })+
355 };
356}
357
358/// The bare body crossref answers a content-negotiation request it cannot
359/// serve with, which is shaped nothing like a `validation-failure`.
360#[derive(serde::Deserialize)]
361struct TransformFailure {
362 /// what went wrong, e.g. `style-not-found`
363 code: String,
364 /// the DOI that was asked for
365 doi: Option<String>,
366 /// the explanation, e.g. `Style [vancouver] does not exist`
367 message: String,
368}
369
370/// Struct for Crossref search API methods
371///
372/// Cloning is cheap and shares the connection pool and the rate limiter, so
373/// concurrent callers should clone one client rather than build several -- see
374/// [`Crossref::rate_limit`].
375#[derive(Debug, Clone)]
376pub struct Crossref {
377 /// use another base url than `api.crossref.org`
378 base_url: String,
379 /// the reqwest client that handles the requests
380 client: Client,
381 /// paces requests against the budget crossref grants, shared between clones
382 limiter: Arc<Limiter>,
383 /// how many times a `429` is retried before giving up
384 max_retries: u32,
385}
386
387impl Crossref {
388 const BASE_URL: &'static str = "https://api.crossref.org";
389
390 /// Constructs a new `CrossrefBuilder`.
391 ///
392 /// This is the same as `Crossref::builder()`.
393 pub fn builder() -> CrossrefBuilder {
394 CrossrefBuilder::new()
395 }
396
397 /// The url every route is appended to, `https://api.crossref.org` unless
398 /// [`CrossrefBuilder::base_url`] said otherwise.
399 pub fn base_url(&self) -> &str {
400 &self.base_url
401 }
402
403 /// The request budget crossref last reported for this client.
404 ///
405 /// Crossref sends the budget on every response and the client paces itself
406 /// against it, so before the first request this is the assumed
407 /// [`RateLimit::CONSERVATIVE`] (or whatever [`CrossrefBuilder::rate_limit`]
408 /// was given) and afterwards it is what crossref actually granted.
409 pub fn rate_limit(&self) -> RateLimit {
410 self.limiter.rate()
411 }
412
413 /// The pool crossref sorted the last request into, from `x-api-pool`.
414 ///
415 /// `polite` if [`CrossrefBuilder::polite`] worked, `plus` for a Plus token,
416 /// otherwise `public`. [`None`] before the first request.
417 pub fn api_pool(&self) -> Option<String> {
418 self.limiter.pool()
419 }
420
421 // generate all functions to query combined endpoints
422 impl_combined_works_query!(funder_works Funders, member_works Members,
423 type_works Types, journal_works Journals, prefix_works Prefixes,);
424
425 /// Transforms the `CrossrefQuery` in the request route and executes the request
426 ///
427 /// # Errors
428 ///
429 /// If crossref could not resolve the route, a `ResourceNotFound` error is returned.
430 /// Also fails if the json response body could not be parsed into `Response`.
431 /// Fails if there was an error in reqwest executing the request [::reqwest::RequestBuilder::send]
432 async fn get_response<T: CrossrefQuery>(&self, query: &T) -> Result<Response> {
433 let url = query.to_url(&self.base_url)?;
434 let response = self.send(&url).await?;
435
436 // crossref answers an unresolvable route with a plain-text body, which
437 // would otherwise surface as an opaque deserialization failure
438 if response.status() == StatusCode::NOT_FOUND {
439 return Err(Error::ResourceNotFound {
440 resource: Box::new(query.clone().resource_component()),
441 });
442 }
443
444 // deserialized here rather than through `reqwest`'s `json()` so a
445 // shape crossref changed surfaces as `Error::Serde`, which names the
446 // field that failed
447 let body = Self::into_success(response).await?.bytes().await?;
448 serde_json::from_slice(&body).map_err(|error| Error::Serde { error })
449 }
450
451 /// Sends a `GET`, pacing it against the rate limit and retrying a `429`.
452 ///
453 /// Waits for a slot from the shared [`Limiter`] first, then feeds the
454 /// budget crossref reports back into it. A `429` means the budget we
455 /// believed in was wrong, so the whole client backs off -- for as long as
456 /// `retry-after` asks, or exponentially from the reported interval -- and
457 /// the request is sent again up to [`CrossrefBuilder::max_retries`] times.
458 async fn send(&self, url: &str) -> Result<reqwest::Response> {
459 self.send_with(url, |request| request).await
460 }
461
462 /// [`Crossref::send`], with `customize` applied to the request first.
463 async fn send_with(
464 &self,
465 url: &str,
466 customize: impl Fn(reqwest::RequestBuilder) -> reqwest::RequestBuilder,
467 ) -> Result<reqwest::Response> {
468 let mut attempt = 0u32;
469 loop {
470 self.limiter.acquire().await;
471 tracing::debug!(%url, attempt, "crossref request");
472
473 let response = customize(self.client.get(url)).send().await?;
474 self.limiter.observe(response.headers());
475
476 if response.status() != StatusCode::TOO_MANY_REQUESTS {
477 return Ok(response);
478 }
479
480 let limit = self.limiter.rate();
481 let delay = retry_after(response.headers())
482 .unwrap_or_else(|| limit.interval * 2u32.pow(attempt.min(5)));
483 self.limiter.back_off(delay);
484 attempt += 1;
485
486 if attempt > self.max_retries {
487 tracing::warn!(%url, attempt, "crossref rate limited, retries exhausted");
488 return Err(Error::RateLimited {
489 attempts: attempt,
490 limit,
491 });
492 }
493 tracing::debug!(%url, attempt, ?delay, "crossref rate limited, retrying");
494 }
495 }
496
497 /// Turns a non-success response into the error crossref described.
498 ///
499 /// Crossref answers a bad filter, sort field or field query with a `400`
500 /// and a `validation-failure` body naming what it did not recognise, and an
501 /// unservable content-negotiation format with a `406` and a bare
502 /// `{code, message}` -- both of which
503 /// [`reqwest::Response::error_for_status`] would throw away.
504 async fn into_success(response: reqwest::Response) -> Result<reqwest::Response> {
505 if response.status().is_success() {
506 return Ok(response);
507 }
508
509 // taken before the body is consumed, so the status is still reportable
510 // if the body turns out not to explain itself
511 let status = response.error_for_status_ref().expect_err("not a success");
512 let body = response.text().await.unwrap_or_default();
513
514 if let Ok(Response {
515 message: Message::ValidationFailure(failures),
516 ..
517 }) = serde_json::from_str::<Response>(&body)
518 {
519 return Err(Error::ValidationFailure { failures });
520 }
521 if let Ok(failure) = serde_json::from_str::<TransformFailure>(&body) {
522 return Err(Error::ValidationFailure {
523 failures: vec![Failure {
524 type_: failure.code,
525 value: failure.doi.unwrap_or_default(),
526 message: failure.message,
527 }]
528 .into(),
529 });
530 }
531 Err(status.into())
532 }
533
534 //fn get_response_blocking<T: CrossrefQuery>(&self, query: &T) -> Result<Response> {
535 // let resp = self
536 // .blocking_client
537 // .get(&query.to_url(&self.base_url)?)
538 // .send()?
539 // .text()?;
540 // if resp.starts_with("Resource not found") {
541 // Err(Error::ResourceNotFound {
542 // resource: Box::new(query.clone().resource_component()),
543 // }
544 // .into())
545 // } else {
546 // Ok(serde_json::from_str(&resp)?)
547 // }
548 //}
549
550 /// Return the `Work` items that match a certain query.
551 ///
552 /// To search only by query terms use the convenience query method [`Crossref::works`]
553 ///
554 /// # Example
555 ///
556 /// ```no_run
557 /// use crossref_client::{Crossref, WorksQuery, WorksFilter, FieldQuery};
558 /// # async fn run() -> Result<(), crossref_client::Error> {
559 /// let client = Crossref::builder().build()?;
560 ///
561 /// let query = WorksQuery::new("Machine Learning")
562 /// .filter(WorksFilter::HasOrcid)
563 /// .order(crossref_client::Order::Asc)
564 /// .field_query(FieldQuery::author("Some Author"))
565 /// .sort(crossref_client::Sort::Score);
566 ///
567 /// let works = client.works(query).await?;
568 ///
569 /// # Ok(())
570 /// # }
571 /// ```
572 ///
573 /// # Errors
574 ///
575 /// This method fails if the `works` element expands to a bad route `ResourceNotFound`
576 /// Fails if the response body doesn't have `message` field `MissingMessage`.
577 /// Fails if anything else than a `WorkList` is returned as message `UnexpectedItem`
578 pub async fn works<T: Into<WorkListQuery>>(&self, query: T) -> Result<WorkList> {
579 let resp = self.get_response(&query.into()).await?;
580
581 get_item!(WorkList, resp)
582 }
583
584 /// Return the `Work` that is identified by the `doi`.
585 ///
586 /// # Errors
587 /// This method fails if the doi could not identified `ResourceNotFound`
588 ///
589 pub async fn work(&self, doi: &str) -> Result<Work> {
590 let resp = self
591 .get_response(&Works::Identifier(doi.to_string()))
592 .await?;
593 get_item!(Work, resp).map(|x| *x)
594 }
595
596 /// [Deep paging results](https://github.com/CrossRef/rest-api-doc#deep-paging-with-cursors)
597 /// Deep paging is supported for all queries, that return a list of `Work`, `WorkList`.
598 /// This function returns a new iterator over pages of `Work`, which is returned as bulk of items as a `WorkList` by crossref.
599 /// Usually a single page `WorkList` contains 20 items.
600 ///
601 /// # Example
602 ///
603 /// Iterate over all `Works` linked to search term `Machine Learning`
604 ///
605 /// ```no_run
606 /// use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
607 /// # async fn run() -> Result<(), crossref_client::Error> {
608 /// let client = Crossref::builder().build()?;
609 ///
610 /// let mut pages = client.deep_page(WorksQuery::new("Machine Learning"));
611 /// let mut all_works: Vec<Work> = Vec::new();
612 /// while let Some(page) = pages.next().await {
613 /// let page = page?;
614 /// all_works.extend(page.items);
615 /// }
616 ///
617 /// # Ok(())
618 /// # }
619 /// ```
620 ///
621 /// # Example
622 ///
623 /// Iterate over all the pages (`WorkList`) of the funder with id `funder id` by using a combined query.
624 /// A single `WorkList` usually holds 20 `Work` items.
625 ///
626 /// ```no_run
627 /// use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
628 /// # async fn run() -> Result<(), crossref_client::Error> {
629 /// let client = Crossref::builder().build()?;
630 ///
631 /// let mut pages = client.deep_page(WorksQuery::default().into_combined_query::<Funders>("funder id"));
632 /// let mut all_funder_work_list: Vec<WorkList> = Vec::new();
633 /// while let Some(page) = pages.next().await {
634 /// let page = page?;
635 /// all_funder_work_list.push(page);
636 /// }
637 ///
638 /// # Ok(())
639 /// # }
640 /// ```
641 /// # Example
642 ///
643 /// Iterate over all `Work` items of a specfic funder directly.
644 ///
645 /// ```no_run
646 /// use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
647 /// # async fn run() -> Result<(), crossref_client::Error> {
648 /// let client = Crossref::builder().build()?;
649 ///
650 /// let mut works = client.deep_page(WorksQuery::default()
651 /// .into_combined_query::<Funders>("funder id"))
652 /// .into_work_iter();
653 /// let mut all_works: Vec<Work> = Vec::new();
654 /// while let Some(work) = works.next().await {
655 /// let work = work?;
656 /// all_works.push(work);
657 /// }
658 ///
659 /// # Ok(())
660 /// # }
661 /// ```
662 ///
663 /// # Example
664 ///
665 /// Alternatively deep page without an iterator by handling the cursor directly
666 ///
667 /// ```no_run
668 /// use crossref_client::{Crossref, WorksQuery, WorksFilter};
669 /// # async fn run() -> Result<(), crossref_client::Error> {
670 /// let client = Crossref::builder().build()?;
671 ///
672 /// // request a next-cursor first
673 /// let query = WorksQuery::new("Machine Learning")
674 /// .new_cursor();
675 ///
676 /// let works = client.works(query.clone()).await?;
677 ///
678 /// // this continues from where this first response stopped
679 /// // if no more work items are available then a empty list will be returned
680 /// let deep_works = client.works(
681 /// query.next_cursor(&works.next_cursor.unwrap())
682 /// ).await?;
683 /// # Ok(())
684 /// # }
685 /// ```
686 ///
687 pub fn deep_page<T: Into<WorkListQuery>>(&self, query: T) -> WorkListIterator<'_> {
688 WorkListIterator::new(query.into(), self)
689 }
690
691 /// Re-serialize the work identified by `doi` into another format.
692 ///
693 /// Crossref renders the registered metadata itself, so this never goes
694 /// through [`Work`] and the body is returned verbatim -- BibTeX, RIS, RDF
695 /// or a citation formatted in a [CSL style](Crossref::styles).
696 ///
697 /// # Example
698 ///
699 /// ```no_run
700 /// use crossref_client::{CnFormat, Crossref};
701 /// # async fn run() -> Result<(), crossref_client::Error> {
702 /// # let client = Crossref::builder().build()?;
703 /// let bibtex = client
704 /// .transform("10.1037/0003-066X.59.1.29", &CnFormat::BibTex)
705 /// .await?;
706 ///
707 /// let citation = client
708 /// .transform("10.1037/0003-066X.59.1.29", &CnFormat::bibliography("apa"))
709 /// .await?;
710 /// # Ok(())
711 /// # }
712 /// ```
713 ///
714 /// # Errors
715 ///
716 /// Fails with [`Error::ValidationFailure`] if crossref cannot serve the
717 /// format for this DOI -- an unknown CSL style is the usual cause.
718 pub async fn transform(&self, doi: &str, format: &CnFormat) -> Result<String> {
719 let url = format!("{}/works/{}/transform", self.base_url, doi);
720 let response = self
721 .send_with(&url, |request| {
722 request.header(reqwest::header::ACCEPT, format.accept().as_ref())
723 })
724 .await?;
725
726 Ok(Self::into_success(response).await?.text().await?)
727 }
728
729 /// Return the [CSL styles](https://citationstyles.org) crossref can render
730 /// a citation in, for [`CnFormat::Bibliography`].
731 ///
732 /// Roughly 2 900 of them, in one response.
733 pub async fn styles(&self) -> Result<StyleList> {
734 let response = self.send(&format!("{}/styles", self.base_url)).await?;
735 let body = Self::into_success(response).await?.bytes().await?;
736 let response: Response =
737 serde_json::from_slice(&body).map_err(|error| Error::Serde { error })?;
738
739 get_item!(StyleList, response)
740 }
741
742 /// Return the `Agency` that registers the `Work` identified by the `doi`.
743 ///
744 /// # Errors
745 /// This method fails if the doi could not identified `ResourceNotFound`
746 ///
747 pub async fn work_agency(&self, doi: &str) -> Result<WorkAgency> {
748 let resp = self.get_response(&Works::Agency(doi.to_string())).await?;
749 get_item!(WorkAgency, resp)
750 }
751
752 /// Return the matching `Funders` items.
753 pub async fn funders(&self, funders: FundersQuery) -> Result<FunderList> {
754 let resp = self.get_response(&Funders::Query(funders)).await?;
755 get_item!(FunderList, resp)
756 }
757
758 /// Return the `Funder` for the `id`
759 pub async fn funder(&self, id: &str) -> Result<Funder> {
760 let resp = self
761 .get_response(&Funders::Identifier(id.to_string()))
762 .await?;
763 get_item!(Funder, resp).map(|x| *x)
764 }
765
766 /// Return the matching `Members` items.
767 pub async fn members(&self, members: MembersQuery) -> Result<MemberList> {
768 let resp = self.get_response(&Members::Query(members)).await?;
769 get_item!(MemberList, resp)
770 }
771
772 /// Return the `Member` for the `id`
773 pub async fn member(&self, member_id: &str) -> Result<Member> {
774 let resp = self
775 .get_response(&Members::Identifier(member_id.to_string()))
776 .await?;
777 get_item!(Member, resp).map(|x| *x)
778 }
779
780 /// Return the `Prefix` for the `id`
781 pub async fn prefix(&self, id: &str) -> Result<Prefix> {
782 let resp = self
783 .get_response(&Prefixes::Identifier(id.to_string()))
784 .await?;
785 get_item!(Prefix, resp)
786 }
787 /// Return a specific `Journal`
788 pub async fn journal(&self, id: &str) -> Result<Journal> {
789 let resp = self
790 .get_response(&Journals::Identifier(id.to_string()))
791 .await?;
792
793 get_item!(Journal, resp).map(|x| *x)
794 }
795
796 /// Return the matching `Journal` items.
797 ///
798 /// # Example
799 ///
800 /// ```no_run
801 /// use crossref_client::{Crossref, JournalsQuery, ResultControl};
802 /// # async fn run() -> Result<(), crossref_client::Error> {
803 /// # let client = Crossref::builder().build()?;
804 /// let journals = client
805 /// .journals(JournalsQuery::new("Economic Geography").result_control(ResultControl::Rows(10)))
806 /// .await?;
807 /// # Ok(())
808 /// # }
809 /// ```
810 pub async fn journals(&self, journals: JournalsQuery) -> Result<JournalList> {
811 let resp = self.get_response(&Journals::Query(journals)).await?;
812 get_item!(JournalList, resp)
813 }
814
815 /// Return the licenses works in the crossref metadata are published under,
816 /// each with the number of works that carry it.
817 ///
818 /// # Example
819 ///
820 /// ```no_run
821 /// use crossref_client::{Crossref, LicensesQuery, ResultControl};
822 /// # async fn run() -> Result<(), crossref_client::Error> {
823 /// # let client = Crossref::builder().build()?;
824 /// let licenses = client
825 /// .licenses(LicensesQuery::new("creative commons").result_control(ResultControl::Rows(10)))
826 /// .await?;
827 ///
828 /// for license in &licenses.items {
829 /// println!("{:>8} {}", license.work_count, license.url);
830 /// }
831 /// # Ok(())
832 /// # }
833 /// ```
834 pub async fn licenses(&self, licenses: LicensesQuery) -> Result<LicenseList> {
835 let resp = self.get_response(&Licenses::Query(licenses)).await?;
836 get_item!(LicenseList, resp)
837 }
838
839 /// Return all available `Type`
840 pub async fn types(&self) -> Result<TypeList> {
841 let resp = self.get_response(&Types::All).await?;
842 get_item!(TypeList, resp)
843 }
844
845 /// Return the `Type` for the `id`
846 pub async fn type_(&self, id: &Type) -> Result<CrossrefType> {
847 let resp = self
848 .get_response(&Types::Identifier(id.id().to_string()))
849 .await?;
850 get_item!(Type, resp)
851 }
852
853 /// Get a random set of DOIs
854 ///
855 /// # Example
856 ///
857 /// ```no_run
858 /// use crossref_client::Crossref;
859 /// # async fn run() -> Result<(), crossref_client::Error> {
860 /// # let client = Crossref::builder().build()?;
861 /// // this will return 10 random dois from the crossref api
862 /// let random_dois = client.random_dois(10).await?;
863 /// # Ok(())
864 /// # }
865 /// ```
866 pub async fn random_dois(&self, len: usize) -> Result<Vec<String>> {
867 self.works(WorksQuery::random(len))
868 .await
869 .map(|x| x.items.into_iter().map(|x| x.doi).collect())
870 }
871}
872
873/// A `CrossrefBuilder` can be used to create `Crossref` with additional config.
874///
875/// # Example
876///
877/// ```no_run
878/// use crossref_client::Crossref;
879/// # async fn run() -> Result<(), crossref_client::Error> {
880///
881/// let client = Crossref::builder()
882/// .polite("polite@example.com")
883/// .token("your token")
884/// .build()?;
885/// # Ok(())
886/// # }
887/// ```
888/// Every setter accepts `Option`, so options that are themselves optional --
889/// a CLI flag, a config field -- can be passed straight through:
890///
891/// ```no_run
892/// # use crossref_client::Crossref;
893/// # fn run(email: Option<String>) -> Result<(), crossref_client::Error> {
894/// let client = Crossref::builder().polite(email.as_deref()).build()?;
895/// # Ok(())
896/// # }
897/// ```
898#[derive(Debug, Default)]
899pub struct CrossrefBuilder {
900 /// [Good manners = more reliable service.](https://github.com/CrossRef/rest-api-doc#good-manners--more-reliable-service)
901 ///
902 /// will add a `User-Agent` header by default with with the `email` email.
903 /// crossref can contact you if your script misbehaves
904 /// this will get you directed to the "polite pool"
905 user_agent: Option<String>,
906 /// the token for the Crossref Plus service will be included as `Authorization` header
907 /// This token will ensure that said requests get directed to a pool of machines that are reserved for "Plus" SLA users.
908 plus_token: Option<String>,
909 /// use a different base url than `Crossref::BASE_URL` <https://api.crossref.org>
910 base_url: Option<String>,
911 /// the budget to assume until crossref reports one
912 rate_limit: Option<RateLimit>,
913 /// how many times a `429` is retried
914 max_retries: Option<u32>,
915}
916
917impl CrossrefBuilder {
918 /// How many times a `429` is retried before [`Error::RateLimited`] is
919 /// returned, when the builder was not told otherwise.
920 const DEFAULT_MAX_RETRIES: u32 = 3;
921
922 /// Constructs a new `CrossrefBuilder`.
923 ///
924 /// This is the same as `Crossref::builder()`.
925 pub fn new() -> CrossrefBuilder {
926 CrossrefBuilder::default()
927 }
928
929 /// Be polite: identify yourself by email and get routed to crossref's
930 /// [polite pool](https://api.crossref.org/swagger-ui/index.html#/Etiquette).
931 ///
932 /// Sends a `User-Agent` in the shape crossref asks for, e.g.
933 /// `crossref-client/0.2.0 (https://github.com/…; mailto:you@example.com)`.
934 /// Anonymous requests share a rate-limited pool and are the usual cause of
935 /// `429` responses; check where you landed with
936 /// [`Crossref::api_pool`].
937 ///
938 /// Use [`CrossrefBuilder::user_agent`] instead if you want to send your own
939 /// application's name; include `mailto:<email>` in it to stay in the pool.
940 pub fn polite<'a>(mut self, email: impl Into<Option<&'a str>>) -> Self {
941 if let Some(email) = email.into() {
942 self.user_agent = Some(format!(
943 "{}/{} ({}; mailto:{})",
944 env!("CARGO_PKG_NAME"),
945 env!("CARGO_PKG_VERSION"),
946 env!("CARGO_PKG_REPOSITORY"),
947 email
948 ));
949 }
950 self
951 }
952
953 /// set the user agent directly
954 pub fn user_agent<'a>(mut self, user_agent: impl Into<Option<&'a str>>) -> Self {
955 self.user_agent = user_agent.into().map(str::to_owned);
956 self
957 }
958
959 /// set a crossref plus service API token
960 pub fn token<'a>(mut self, token: impl Into<Option<&'a str>>) -> Self {
961 self.plus_token = token.into().map(str::to_owned);
962 self
963 }
964
965 /// Send requests somewhere other than `https://api.crossref.org`.
966 ///
967 /// Routes are appended verbatim, so the url must not end in a `/`. Mainly
968 /// useful for pointing the client at a mock or a proxy in tests.
969 pub fn base_url<'a>(mut self, base_url: impl Into<Option<&'a str>>) -> Self {
970 self.base_url = base_url.into().map(str::to_owned);
971 self
972 }
973
974 /// The request budget to assume until crossref reports its own.
975 ///
976 /// Defaults to [`RateLimit::CONSERVATIVE`]. Crossref sends the real budget
977 /// on every response and the client follows it from then on, so this only
978 /// paces the first few requests.
979 pub fn rate_limit(mut self, rate_limit: impl Into<Option<RateLimit>>) -> Self {
980 self.rate_limit = rate_limit.into();
981 self
982 }
983
984 /// How many times a `429` is retried before giving up with
985 /// [`Error::RateLimited`]. Defaults to 3; `0` disables retrying.
986 pub fn max_retries(mut self, max_retries: impl Into<Option<u32>>) -> Self {
987 self.max_retries = max_retries.into();
988 self
989 }
990
991 /// Returns a `Crossref` that uses this `CrossrefBuilder` configuration.
992 /// # Errors
993 ///
994 /// This will fail if TLS backend cannot be initialized see [reqwest::ClientBuilder::build]
995 pub fn build(self) -> Result<Crossref> {
996 use reqwest::header;
997 let mut headers = header::HeaderMap::new();
998 if let Some(agent) = &self.user_agent {
999 headers.insert(
1000 header::USER_AGENT,
1001 header::HeaderValue::from_str(agent).map_err(|_| Error::Config {
1002 msg: format!("failed to create User Agent header for `{}`", agent),
1003 })?,
1004 );
1005 }
1006 if let Some(token) = &self.plus_token {
1007 headers.insert(
1008 header::AUTHORIZATION,
1009 header::HeaderValue::from_str(token).map_err(|_| Error::Config {
1010 msg: format!("failed to create AUTHORIZATION header for `{}`", token),
1011 })?,
1012 );
1013 }
1014 let client = reqwest::Client::builder()
1015 .default_headers(headers)
1016 .build()
1017 .map_err(|_| Error::Config {
1018 msg: "failed to initialize TLS backend".to_string(),
1019 })?;
1020
1021 Ok(Crossref {
1022 base_url: self
1023 .base_url
1024 .unwrap_or_else(|| Crossref::BASE_URL.to_string()),
1025 client,
1026 limiter: Arc::new(Limiter::new(self.rate_limit.unwrap_or_default())),
1027 max_retries: self.max_retries.unwrap_or(Self::DEFAULT_MAX_RETRIES),
1028 })
1029 }
1030}
1031
1032/// Allows iterating of deep page work request
1033pub struct WorkListIterator<'a> {
1034 /// the query
1035 query: WorkListQuery,
1036 /// performs each request
1037 client: &'a Crossref,
1038 /// whether the iterator should finish next iteration
1039 finish_next_iteration: bool,
1040}
1041
1042impl<'a> WorkListIterator<'a> {
1043 /// Create an iterator that deep pages `query` through `client`.
1044 pub fn new(query: WorkListQuery, client: &'a Crossref) -> Self {
1045 Self {
1046 query,
1047 client,
1048 finish_next_iteration: false,
1049 }
1050 }
1051
1052 /// Flatten the paged results into an iterator over individual [`Work`] items.
1053 ///
1054 /// Pages are fetched lazily, one request at a time, as the buffer drains.
1055 pub fn into_work_iter(self) -> WorkIterator<'a> {
1056 WorkIterator {
1057 pages: self,
1058 buffer: Vec::new().into_iter(),
1059 }
1060 }
1061}
1062
1063/// Yields individual [`Work`] items across the deep paged [`WorkList`] pages.
1064///
1065/// Created by [`WorkListIterator::into_work_iter`].
1066pub struct WorkIterator<'a> {
1067 pages: WorkListIterator<'a>,
1068 buffer: std::vec::IntoIter<Work>,
1069}
1070
1071impl async_iterator::Iterator for WorkIterator<'_> {
1072 type Item = Result<Work>;
1073
1074 async fn next(&mut self) -> Option<Self::Item> {
1075 loop {
1076 if let Some(work) = self.buffer.next() {
1077 return Some(Ok(work));
1078 }
1079 // `WorkListIterator` stops on the first empty page and after an
1080 // error, so this terminates
1081 match self.pages.next().await? {
1082 Ok(page) => self.buffer = page.items.into_iter(),
1083 Err(err) => return Some(Err(err)),
1084 }
1085 }
1086 }
1087}
1088
1089impl async_iterator::Iterator for WorkListIterator<'_> {
1090 type Item = Result<WorkList>;
1091
1092 async fn next(&mut self) -> Option<Self::Item> {
1093 if self.finish_next_iteration {
1094 return None;
1095 }
1096
1097 {
1098 let control = &mut self.query.query_mut().result_control;
1099
1100 // if no result control is set, set a new cursor
1101 if control.is_none() {
1102 *control = Some(WorkResultControl::new_cursor());
1103 }
1104 }
1105
1106 let page = match self.client.get_response(&self.query).await {
1107 Ok(resp) => get_item!(WorkList, resp),
1108 Err(err) => Err(err),
1109 };
1110
1111 let worklist = match page {
1112 Ok(worklist) => worklist,
1113 Err(err) => {
1114 // a transient `429` or an unparsable page used to end the
1115 // iteration silently, which a caller cannot tell apart from
1116 // having crawled everything -- surface it and stop
1117 self.finish_next_iteration = true;
1118 return Some(Err(err));
1119 }
1120 };
1121
1122 if let Some(cursor) = &worklist.next_cursor {
1123 match &mut self.query.query_mut().result_control {
1124 Some(WorkResultControl::Cursor { token, .. }) => {
1125 // use the received cursor token in next iteration
1126 *token = Some(cursor.clone())
1127 }
1128 Some(WorkResultControl::Standard(_)) => {
1129 // standard result control was set, don't deep page and return next iteration
1130 self.finish_next_iteration = true;
1131 }
1132 _ => (),
1133 }
1134 } else {
1135 // no cursor received, end next iteration
1136 self.finish_next_iteration = true;
1137 }
1138
1139 if worklist.items.is_empty() {
1140 None
1141 } else {
1142 Some(Ok(worklist))
1143 }
1144 }
1145}