https://github.com/zacharygolba/json-api-rs
Idiomatic types for building a robust JSON API with Rust
https://github.com/zacharygolba/json-api-rs
json-api rocket rust serde
Last synced: 3 months ago
JSON representation
Idiomatic types for building a robust JSON API with Rust
- Host: GitHub
- URL: https://github.com/zacharygolba/json-api-rs
- Owner: zacharygolba
- License: apache-2.0
- Created: 2017-10-07T22:34:22.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-05-27T20:53:41.000Z (almost 7 years ago)
- Last Synced: 2025-01-30T19:07:30.915Z (4 months ago)
- Topics: json-api, rocket, rust, serde
- Language: Rust
- Homepage: https://crates.io/crates/json-api
- Size: 141 KB
- Stars: 26
- Watchers: 3
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# json-api
[](https://circleci.com/gh/zacharygolba/json-api-rs/tree/master) [](https://ci.appveyor.com/project/zacharygolba/json-api-rs/branch/master) [](https://codecov.io/gh/zacharygolba/json-api-rs) [](https://crates.io/crates/json-api)
Idiomatic types for building a robust [JSON API](http://jsonapi.org/).
## Features
### Serialization DSL
You can define a `Resource` using a friendly, declarative dsl.
#### Concise
```rust
#[macro_use]
extern crate json_api;
struct Post {
id: u64,
body: String,
title: String,
author: Option,
comments: Vec,
}
resource!(Post, |&self| {
// Define the id.
id self.id;
// Define the resource "type"
kind "posts";
// Define attributes with a comma seperated list of field names.
attrs body, title;
// Define relationships with a comma seperated list of field names.
has_one author;
has_many comments;
});
```
#### Flexible
```rust
#[macro_use]
extern crate json_api;
struct Post {
id: u64,
body: String,
title: String,
author: Option,
comments: Vec,
}
resource!(Post, |&self| {
kind "articles";
id self.id;
attrs body, title;
// Define a virtual attribute with an expression
attr "preview", {
self.body
.chars()
.take(140)
.collect::()
}
// Define a relationship with granular detail
has_one "author", {
// Data for has one should be Option<&T> where T: Resource
data self.author.as_ref();
// Define relationship links
link "self", format!("/articles/{}/relationships/author", self.id);
link "related", format!("/articles/{}/author", self.id);
// Define arbitrary meta members with a block expression
meta "read-only", true
}
// Define a relationship with granular detail
has_many "comments", {
// Data for has one should be an Iterator where T: Resource
data self.comments.iter();
// Define relationship links
link "self", format!("/articles/{}/relationships/comments", self.id);
link "related", format!("/articles/{}/comments", self.id);
// Define arbitrary meta members with a block expression
meta "total", {
self.comments.len()
}
}
// You can also define links with granular details as well
link "self", {
href format!("/articles/{}", self.id);
}
// Define arbitrary meta members an expression
meta "copyright", self.author.as_ref().map(|user| {
format!("© 2017 {}", user.full_name())
});
});
```
### Rocket Support
The [json-api-rocket](https://crates.io/crates/json-api-rocket) crate provides responders
as well as a fairing for catching errors and returning [JSON API](http://jsonapi.org)
error documents.
```rust
#![feature(plugin)]
#![plugin(rocket_codegen)]
#[macro_use]
extern crate json_api;
extern crate json_api_rocket;
extern crate rocket;
mod models;
use json_api_rocket::JsonApiFairing;
use json_api_rocket::response::{Collection, Member};
use models::Article;
#[get("/")]
fn collection() -> Collection {
(1..25).map(Article::new).collect()
}
#[get("/")]
fn member(id: u64) -> Member {
Member(Article::new(id))
}
fn main() {
rocket::ignite()
.attach(JsonApiFairing)
.mount("/articles", routes![collection, member])
.launch();
}
```
## License
Licensed under either of
* Apache License, Version 2.0
([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license
([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.