Skip to main content

Crate crossref_client

Crate crossref_client 

Source
Expand description

An async client for the Crossref REST API.

crossref-client is a hard fork of crossref-rs and has diverged substantially from it; changes are not upstreamed.

When a route answers something this crate did not expect, the api documents itself in the swagger UI and in CrossRef/rest-api-doc, and its bugs and in-flight changes are tracked in the open on crossref’s own issue board.

The Crossref client provides methods matching the Crossref API routes:

  • works - /works route
  • members - /members route
  • prefixes - /prefixes route
  • funders - /funders route
  • journals - /journals route
  • licenses - /licenses route
  • types - /types route
  • agency - /works/{doi}/agency get DOI minting agency

§Usage

§Create a Crossref client:

let client = Crossref::builder().build()?;

If you have an Authorization token for Crossref’s Plus service:

let client = Crossref::builder()
.token("token")
.build()?;

Encouraged to use the The Polite Pool:

Good manners = more reliable service

To get into Crossref’s polite pool include a email address

let client = Crossref::builder()
    .polite("polite@example.com")
    .token("your token")
    .build()?;

§Constructing Queries

Not all components support queries and there are custom available parameters for each route that supports querying. 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 and field queries.

Otherwise creating queries works the same for all resource components:

let query = WorksQuery::new("Machine Learning")
// field queries supported for `Works`
.field_query(FieldQuery::author("Some Author"))
// filters are specific for each resource component
.filter(WorksFilter::HasOrcid)
.order(Order::Asc)
.sort(Sort::Score);

§Get Records

See this table for a detailed overview of the major components.

There are 3 available targets:

  • standalone resource components: /works, /members, etc. that return a list list of the corresponding items and can be specified with queries
  • Resource component with identifiers: /works/{doi}?<query>,/members/{member_id}?<query>, etc. that returns a single item if found.
  • 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.

This resembles in the enums of the resource components, eg. for Members:

pub enum Members {
    /// target a specific member at `/members/{id}`
    Identifier(String),
    /// target all members that match the query at `/members?query...`
    Query(MembersQuery),
    /// target a `Work` for a specific member at `/members/{id}/works?query..`
    Works(WorksIdentQuery),
}

All options are supported by the client:

Single Item by DOI (ID)

Analogous methods exist for all resource components

let work = client.work("10.1037/0003-066X.59.1.29").await?;

let agency = client.work_agency("10.1037/0003-066X.59.1.29").await?;

let funder = client.funder("funder_id").await?;

let member = client.member("member_id").await?;

Query

let query = WorksQuery::new("Machine Learning");

// one page of the matching results
let works = client.works(query).await?;

Alternatively insert a free form query term directly


// one page of the matching results
let works = client.works("Machine Learning").await?;

Combining Routes with the Works route

For each resource component other than Works there exist methods to append a WorksQuery with the ID option /members/{member_id}/works?<query>?

let works = client.member_works( WorksQuery::new("machine learning")
.sort(Sort::Score).into_ident("member_id")).await?;

This would be the same as using the Crossref::works method by supplying the combined type

let works = client.works(WorksQuery::new("machine learning")
    .sort(Sort::Score)
    .into_combined_query::<Members>("member_id")).await?;

** Deep paging for Works ** Deep paging results Deep paging is supported for all queries, that return a list of Work, WorkList. This function returns a new iterator over pages of Work, which is returned as bulk of items as a WorkList by crossref. Usually a single page WorkList contains 20 items.

§Example

Iterate over all Works linked to search term Machine Learning

use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
let client = Crossref::builder().build()?;

let mut pages = client.deep_page(WorksQuery::new("Machine Learning"));
let mut all_works: Vec<Work> = Vec::new();
while let Some(page) = pages.next().await {
    let page = page?;
    all_works.extend(page.items);
}

Which can be simplified to

use crossref_client::{AsyncIterator, Crossref, WorksQuery, Work};
let client = Crossref::builder().build()?;

let mut works = client.deep_page("Machine Learning").into_work_iter();
let mut all_works: Vec<Work> = Vec::new();
while let Some(work) = works.next().await {
    let work = work?;
    all_works.push(work);
}

§Example

Iterate over all the pages (WorkList) of the funder with id funder id by using a combined query. A single WorkList usually holds 20 Work items.

use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
let client = Crossref::builder().build()?;

let mut pages = client.deep_page(WorksQuery::default().into_combined_query::<Funders>("funder id"));
let mut all_funder_work_list: Vec<WorkList> = Vec::new();
while let Some(page) = pages.next().await {
    let page = page?;
    all_funder_work_list.push(page);
}

§Example

Iterate over all Work items of a specfic funder directly.

use crossref_client::{AsyncIterator, Crossref, Funders, WorksQuery, Work, WorkList};
let client = Crossref::builder().build()?;

let mut works = client.deep_page(WorksQuery::default()
        .into_combined_query::<Funders>("funder id"))
        .into_work_iter();
let mut all_works: Vec<Work> = Vec::new();
while let Some(work) = works.next().await {
    let work = work?;
    all_works.push(work);
}

Re-exports§

pub use self::query::facet::Facet;
pub use self::query::facet::FacetCount;
pub use self::query::funders::Funders;
pub use self::query::funders::FundersFilter;
pub use self::query::funders::FundersQuery;
pub use self::query::members::Members;
pub use self::query::members::MembersFilter;
pub use self::query::members::MembersQuery;
pub use self::query::Journals;
pub use self::query::JournalsQuery;
pub use self::query::Licenses;
pub use self::query::LicensesQuery;
pub use self::query::Prefixes;
pub use self::query::Type;
pub use self::query::Types;
pub use self::query::Visibility;
pub use self::query::WorksComponent;
pub use self::response::CrossrefType;
pub use self::response::Failure;
pub use self::response::Failures;
pub use self::response::Funder;
pub use self::response::FunderList;
pub use self::response::Journal;
pub use self::response::JournalList;
pub use self::response::LicenseCount;
pub use self::response::LicenseList;
pub use self::response::Member;
pub use self::response::MemberList;
pub use self::response::MessageType;
pub use self::response::StyleList;
pub use self::response::TypeList;
pub use self::response::Work;
pub use self::response::WorkAgency;
pub use self::response::WorkList;

Modules§

cn
content negotiation Content negotiation: a work’s metadata in a format other than crossref json.
limit
client side rate limiting Client side rate limiting.
query
provides types to construct a specific query
response
provides the response types of the crossref api

Structs§

Affiliation
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. an institution a contributor is affiliated with
Agency
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. the registration agency that minted a DOI, e.g. crossref or datacite
Assertion
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. a Crossmark claim the publisher made about the work, e.g. its peer review status or funding
AssertionGroup
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. the heading a set of Assertions is displayed under
ClinicalTrialNumber
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. a clinical trial the work reports on
ContentDomain
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work.
Contributor
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. someone credited on the work: an author, editor, chair or translator
Crossref
Struct for Crossref search API methods
CrossrefBuilder
A CrossrefBuilder can be used to create Crossref with additional config.
Date
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. represents full date information for an item
DateParts
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. Helper struct to represent dates in the cross ref api as nested arrays of numbers
Explanation
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. where a Crossmark assertion is explained
FundingBody
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. a body that funded the work, and the awards it made
ISSN
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. ISSN info for the Work
InstitutionId
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. an identifier for an institution, as deposited on an Affiliation
Issue
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. the issue of a journal a work appeared in
License
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. how the Work is licensed
PartialDate
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. represents an incomplete date only consisting of year or year and month
RateLimit
The request budget crossref grants a client.
Reference
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work.
RelatedItems
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The related items of one relation kind.
Relation
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work.
ResourceLink
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. metadata about a related resource
Review
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work.
Update
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. metadata about when the Work entry was updated
WorkIterator
Yields individual Work items across the deep paged WorkList pages.
WorkListIterator
Allows iterating of deep page work request
WorksIdentQuery
Target Works as secondary resource component
WorksQuery
Used to construct a query that targets crossref Works elements

Enums§

CnFormat
A format crossref will re-serialize a work into.
Component
Major resource components supported by the Crossref API
DateField
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. Helper struct to capture all possible occurrences of dates in the crossref api, a nested Vec of numbers
Error
All different error types this crate uses.
FieldQuery
Matches against one field of a work’s metadata rather than all of it. Available on the /works route only.
FilterParseError
Why a name and value are not a filter a route takes, as WorksFilter::from_name reports it.
Order
Determines how results should be sorted
ResultControl
tells crossref how many items shall be returned or where to start
Sort
Results from a list response can be sorted by applying the sort and order parameters.
WorkElement
A field of a Work that a query can ask crossref to return.
WorkListQuery
Wraps queries that target WorkList, either directly or combined
WorkResultControl
limits from where and how many Work items should be returned
Works
Retrieve a publication by DOI
WorksFilter
Narrows a /works query. Every filter is ANDed with the others.

Traits§

AsyncIterator
The async iterator trait implemented by WorkListIterator.
CrossrefQuery
root level trait to construct full crossref api request urls
CrossrefRoute
represents elements that constructs parts of the crossref request url

Type Aliases§

Relations
The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The types that appear in the public fields of a Work, re-exported so a caller of Crossref::works can name them without reaching into response::work. The relations a work asserts or is the object of, keyed by relation name.
Result
A type alias for handling errors throughout crossref.