1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
//! This is documentation for the `jsonapi` crate.
//! The crate is meant to be used for serializing, deserializing and validating
//! [JSON:API] requests and responses.
//!
//! [JSON:API]: https://jsonapi.org/
//! [serde]: https://serde.rs
//! [JsonApiDocument]: api/struct.JsonApiDocument.html
//! [Resource]: api/struct.Resource.html
//! [jsonapi_model]: macro.jsonapi_model.html
//!
//! ## Examples
//!
//! ### Basic Usage with Macro
//!
//! Using the [`jsonapi_model!`][jsonapi_model] macro a struct can be converted
//! into a [`JsonApiDocument`][JsonApiDocument] or [`Resource`][Resource]. It is
//! required that the struct have an `id` property whose type is `String`. The
//! second argument in the [`jsonapi_model!`][jsonapi_model] marco defines the
//! `type` member as required by the [JSON:API] specification
//!
//! ```rust
//! #[macro_use] extern crate serde_derive;
//! #[macro_use] extern crate jsonapi;
//! use jsonapi::api::*;
//! use jsonapi::model::*;
//!
//! #[derive(Debug, PartialEq, Serialize, Deserialize)]
//! struct Flea {
//! id: String,
//! name: String,
//! };
//!
//! jsonapi_model!(Flea; "flea");
//!
//! let example_flea = Flea {
//! id: "123".into(),
//! name: "Mr.Flea".into(),
//! };
//!
//! // Convert into a `JsonApiDocument`
//! let doc = example_flea.to_jsonapi_document();
//! assert!(doc.is_valid());
//!
//! // Convert into a `Resource`
//! let resource = example_flea.to_jsonapi_resource();
//! ```
//!
//! ### Deserializing a JSON:API Document
//!
//! Deserialize a JSON:API document using [serde] by explicitly declaring the
//! variable type in `Result`
//!
//! ```rust
//! let serialized = r#"
//! {
//! "data": [{
//! "type": "articles",
//! "id": "1",
//! "attributes": {
//! "title": "JSON:API paints my bikeshed!",
//! "body": "The shortest article. Ever."
//! },
//! "relationships": {
//! "author": {
//! "data": {"id": "42", "type": "people"}
//! }
//! }
//! }],
//! "included": [
//! {
//! "type": "people",
//! "id": "42",
//! "attributes": {
//! "name": "John"
//! }
//! }
//! ]
//! }"#;
//! let data: Result<Resource, serde_json::Error> = serde_json::from_str(&serialized);
//! assert_eq!(data.is_ok(), true);
//! ```
//!
//! Or parse the `String` directly using the
//! [Resource::from_str](api/struct.Resource.html) trait implementation
//!
//! ```rust
//! let data = Resource::from_str(&serialized);
//! assert_eq!(data.is_ok(), true);
//! ```
//!
//! [`JsonApiDocument`][JsonApiDocument] implements `PartialEq` which allows two
//! documents to be compared for equality. If two documents possess the **same
//! contents** the ordering of the attributes and fields within the JSON:API
//! document are irrelevant and their equality will be `true`.
//!
//! ## Testing
//!
//! Run the tests:
//!
//! ```text
//! cargo test
//! ```
//!
//! Run tests with more verbose output:
//!
//! ```text
//! RUST_BACKTRACE=1 cargo test -- --nocapture
//! ```
//!
//! Run tests whenever files are modified using `cargo watch`:
//!
//! ```text
//! RUST_BACKTRACE=1 cargo watch "test -- --nocapture"
//! ```
//!
extern crate serde;
extern crate serde_json;
extern crate serde_derive;
extern crate queryst;
extern crate log;
extern crate error_chain;