crossref_client/cn.rs
1//! Content negotiation: a work's metadata in a format other than crossref json.
2//!
3//! Crossref re-serializes a registered work on request, so a DOI can be pulled
4//! straight out as BibTeX, RIS, RDF or a formatted citation without going
5//! through [`Work`](crate::Work) at all. Pass a [`CnFormat`] to
6//! [`Crossref::transform`](crate::Crossref::transform); the format becomes the
7//! `Accept` header and the body comes back verbatim.
8
9use serde::{Deserialize, Serialize};
10use std::borrow::Cow;
11
12/// A format crossref will re-serialize a work into.
13///
14/// Every variant here was checked against the live api. `application/vnd.datacite.datacite+xml`
15/// is deliberately absent: crossref answers it with a `406`, since it only
16/// serves formats for the DOIs it registers itself.
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18pub enum CnFormat {
19 /// RDF/XML
20 RdfXml,
21 /// RDF in the Turtle syntax
22 Turtle,
23 /// [CSL](https://citationstyles.org) JSON, the standard citeproc shape
24 CiteProcJson,
25 /// crossref's older, non-standard citeproc flavour
26 CiteProcJsonIsh,
27 /// [RIS](https://en.wikipedia.org/wiki/RIS_(file_format)), for reference managers
28 Ris,
29 /// BibTeX
30 BibTex,
31 /// crossref's own deposit schema
32 CrossrefXml,
33 /// crossref's [text and data mining](https://www.crossref.org/documentation/retrieve-metadata/rest-api/text-and-data-mining/)
34 /// schema, which carries the full-text links
35 CrossrefTdm,
36 /// a citation formatted for reading, rendered by crossref itself
37 Bibliography {
38 /// the [CSL style](https://api.crossref.org/styles) to render in, e.g.
39 /// `apa` or `ieee`; crossref answers an unknown one with a `406`.
40 ///
41 /// List what it accepts with [`Crossref::styles`](crate::Crossref::styles).
42 style: String,
43 /// the locale to render in, e.g. `de-DE`. [`None`] leaves it to
44 /// crossref, which uses `en-US`.
45 locale: Option<String>,
46 },
47}
48
49impl CnFormat {
50 /// A citation in the named [CSL style](https://api.crossref.org/styles),
51 /// rendered in crossref's default locale.
52 pub fn bibliography(style: impl Into<String>) -> Self {
53 CnFormat::Bibliography {
54 style: style.into(),
55 locale: None,
56 }
57 }
58
59 /// The `Accept` header that asks crossref for this format.
60 pub fn accept(&self) -> Cow<'_, str> {
61 let simple = match self {
62 CnFormat::RdfXml => "application/rdf+xml",
63 CnFormat::Turtle => "text/turtle",
64 CnFormat::CiteProcJson => "application/vnd.citationstyles.csl+json",
65 CnFormat::CiteProcJsonIsh => "application/citeproc+json",
66 CnFormat::Ris => "application/x-research-info-systems",
67 CnFormat::BibTex => "application/x-bibtex",
68 CnFormat::CrossrefXml => "application/vnd.crossref.unixref+xml",
69 CnFormat::CrossrefTdm => "application/vnd.crossref.unixsd+xml",
70 CnFormat::Bibliography { style, locale } => {
71 let mut accept = format!("text/x-bibliography; style={style}");
72 if let Some(locale) = locale {
73 accept.push_str("; locale=");
74 accept.push_str(locale);
75 }
76 return Cow::Owned(accept);
77 }
78 };
79 Cow::Borrowed(simple)
80 }
81}
82
83#[cfg(test)]
84mod tests {
85 use super::*;
86
87 /// One of every variant, for the tests below.
88 fn one_of_each() -> Vec<CnFormat> {
89 vec![
90 CnFormat::RdfXml,
91 CnFormat::Turtle,
92 CnFormat::CiteProcJson,
93 CnFormat::CiteProcJsonIsh,
94 CnFormat::Ris,
95 CnFormat::BibTex,
96 CnFormat::CrossrefXml,
97 CnFormat::CrossrefTdm,
98 CnFormat::bibliography("apa"),
99 ]
100 }
101
102 #[test]
103 fn no_two_formats_ask_for_the_same_thing() {
104 let mut accepts: Vec<_> = one_of_each()
105 .iter()
106 .map(|f| f.accept().to_string())
107 .collect();
108 let total = accepts.len();
109 accepts.sort();
110 accepts.dedup();
111
112 assert_eq!(
113 total,
114 accepts.len(),
115 "duplicate `Accept` values: {accepts:?}"
116 );
117 }
118
119 #[test]
120 fn a_style_and_locale_become_accept_parameters() {
121 assert_eq!(
122 "text/x-bibliography; style=apa",
123 CnFormat::bibliography("apa").accept()
124 );
125
126 assert_eq!(
127 "text/x-bibliography; style=apa; locale=de-DE",
128 CnFormat::Bibliography {
129 style: "apa".to_string(),
130 locale: Some("de-DE".to_string()),
131 }
132 .accept()
133 );
134 }
135}