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-/worksroutemembers-/membersrouteprefixes-/prefixesroutefunders-/fundersroutejournals-/journalsroutelicenses-/licensesroutetypes-/typesrouteagency-/works/{doi}/agencyget 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
worksroute: The works component can be appended to other resources:/members/{member_id}/works?<query>etc. that returns a list of matchingWorkitems.
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 ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::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 ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. the registration agency that minted a DOI, e.g.crossrefordatacite - Assertion
- The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. a Crossmark claim the publisher made about the work, e.g. its peer review status or funding - Assertion
Group - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. the heading a set ofAssertions is displayed under - Clinical
Trial Number - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. a clinical trial the work reports on - Content
Domain - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. - Contributor
- The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. someone credited on the work: an author, editor, chair or translator - Crossref
- Struct for Crossref search API methods
- Crossref
Builder - A
CrossrefBuildercan be used to createCrossrefwith additional config. - Date
- The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. represents full date information for an item - Date
Parts - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::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 ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. where a Crossmark assertion is explained - Funding
Body - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::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 ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. ISSN info for theWork - Institution
Id - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. an identifier for an institution, as deposited on anAffiliation - Issue
- The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::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 ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. how theWorkis licensed - Partial
Date - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. represents an incomplete date only consisting of year or year and month - Rate
Limit - The request budget crossref grants a client.
- Reference
- The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. - Related
Items - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::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 ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. - Resource
Link - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. metadata about a related resource - Review
- The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. - Update
- The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. metadata about when theWorkentry was updated - Work
Iterator - Yields individual
Workitems across the deep pagedWorkListpages. - Work
List Iterator - Allows iterating of deep page work request
- Works
Ident Query - Target
Worksas secondary resource component - Works
Query - Used to construct a query that targets crossref
Workselements
Enums§
- CnFormat
- A format crossref will re-serialize a work into.
- Component
- Major resource components supported by the Crossref API
- Date
Field - The types that appear in the public fields of a
Work, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::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.
- Field
Query - Matches against one field of a work’s metadata rather than all of
it. Available on the
/worksroute only. - Filter
Parse Error - Why a
nameandvalueare not a filter a route takes, asWorksFilter::from_namereports it. - Order
- Determines how results should be sorted
- Result
Control - 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.
- Work
Element - A field of a
Workthat a query can ask crossref to return. - Work
List Query - Wraps queries that target
WorkList, either directly or combined - Work
Result Control - limits from where and how many
Workitems should be returned - Works
- Retrieve a publication by DOI
- Works
Filter - Narrows a
/worksquery. Every filter is ANDed with the others.
Traits§
- Async
Iterator - The async iterator trait implemented by
WorkListIterator. - Crossref
Query - root level trait to construct full crossref api request urls
- Crossref
Route - 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 ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The types that appear in the public fields of aWork, re-exported so a caller ofCrossref::workscan name them without reaching intoresponse::work. The relations a work asserts or is the object of, keyed by relation name. - Result
- A type alias for handling errors throughout crossref.