jsonapi_rs/
lib.rs

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

jsonapi_rs/
lib.rs
