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