[−][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 JSON:API Document
Deserialize a JSON:API 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 JSON:API
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
|