[−][src]Crate jsonapi
This is documentation for the jsonapi
crate.
The crate is meant to be used for serializing, deserializing and validating
JSON:API requests and responses.
Examples
Basic Usage with Macro
Using the jsonapi_model!
macro a struct can be converted
into a JsonApiDocument
or Resource
. It is
required that the struct have an id
property whose type is String
. The
second argument in the jsonapi_model!
marco defines the
type
member as required by the JSON:API specification
#[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 JSONAPI Document
Deserialize a JSONAPI document using serde by explicitly declaring the
variable type in Result
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 trait implementation
let data = Resource::from_str(&serialized);
assert_eq!(data.is_ok(), true);
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 JSONAPI
document are irrelevant and their equality will be true
.
Testing
Run the tests:
cargo test
Run tests with more verbose output:
RUST_BACKTRACE=1 cargo test -- --nocapture
Run tests whenever files are modified using cargo watch
:
RUST_BACKTRACE=1 cargo watch "test -- --nocapture"
Modules
api | Defines custom types and structs primarily that composite the JSON:API document |
array | Defines trait and implementations that allow a |
errors | |
model | Defines the |
query |
Macros
jsonapi_model | When applied this macro implements the
|