[Awesome Rust] jsonapi : Serialize, deserialize and work with JSON-API data

Posted on Edited on In , , Views: Word count in article: 3.6k Reading time ≈ 3 mins.

jsonapi

jsonapi is the Rust library for serialization, deserialization and working with JSON-API data

This is an implementation of the JSON-API v1 specification at jsonapi.org - http://jsonapi.org/.

Installation

Add this crate to your Cargo.toml file,

1
2
3
4
# Cargo.toml

[dependencies]
jsonapi = "*"

Or use the master branch directly from github,

1
2
3
4
# Cargo.toml

[dependencies]
jsonapi = { git = "https://github.com/michiel/jsonapi-rust", branch = "master" }

Examples of most serialization and deserialization cases can be found in the tests/ - https://github.com/michiel/jsonapi-rust/tree/master/tests directory or the documentation - https://docs.rs/jsonapi.

Development

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

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
#[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());

serde_json::to_string(&doc).unwrap()
// {
//     "type": "flea",
//     "id": "1",
//     "attributes": {
//         "id": "123",
//         "name": "Mr.Flea"
//     }
// }

// Convert into a `Resource`
let resource = example_flea.to_jsonapi_resource();

serde_json::to_string(&resource.0).unwrap()
// {
//     "data": [
//         {
//             "type": "flea",
//             "id": "1",
//             "attributes": {
//                 "id": "123",
//                 "name": "Mr.Flea"
//             }
//         }
//     ]
// }

Deserializing a JSON:API Document

Deserialize a JSON:API document using serde by explicitly declaring the variable type in Result

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
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

1
2
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.

References

[1] michiel/jsonapi-rust: Rust library for serialization, deserialization and working with JSON-API data - https://github.com/michiel/jsonapi-rust

[2] jsonapi - Rust - https://docs.rs/jsonapi/latest/jsonapi/

[3] jsonapi - crates.io: Rust Package Registry - https://crates.io/crates/jsonapi

[4] tests/ - https://github.com/michiel/jsonapi-rust/tree/master/tests