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 has many relationship to be optional
errors
model	Defines the JsonApiModel trait. This is primarily used in conjunction with the jsonapi_model! macro to allow arbitrary structs which implement Deserialize to be converted to/from a JsonApiDocument or Resource
query

Macros

jsonapi_model

When applied this macro implements the JsonApiModel trait for the provided type