juniper: A Rust repository from joshmarlow

GraphQL server library for Rust

GraphQL is a data query language developed by Facebook intended to serve mobile and web application frontends. Juniper makes it possible to write GraphQL servers in Rust that are type-safe and blazingly fast.

Juniper does not include a web server - instead it provides building blocks to make integration with existing servers straightforward. It optionally provides a pre-built integration for the Iron and Rocket frameworks.

Installation

Add Juniper to your Cargo.toml:

[dependencies]
juniper = { git = "https://github.com/graphql-rust/juniper" }

If you want Iron integration, you need to depend on the juniper_iron crate. feature flag:

[dependencies]
juniper = { git = "https://github.com/graphql-rust/juniper" }
juniper_iron = { git = "https://github.com/graphql-rust/juniper_iron" }

If you want Rocket integration, you need to depend on the juniper_rocket crate.

Note: Until 0.9 is released, you will need to use a Git dependency to the current master branch.

[dependencies]
juniper = { git = "https://github.com/graphql-rust/juniper" }
juniper_rocket = { git = "https://github.com/graphql-rust/juniper_rocket" }

Building schemas

GraphQL turns the REST paradigm as it's usually implemented on its head: instead of providing a fixed structure of all types and relations in the system, GraphQL defines a schema which your users can query. The schema defines all types, fields, and relations available, while the query defines which fields and relations a user is interested in.

Juniper expects you to already have the types you want to expose in GraphQL as Rust data types. Other than that, it doesn't make any assumptions whether they are stored in a database or just in memory. Exposing a type is a matter of implementing the GraphQLType for your type. To make things a bit easier, Juniper comes with a set of macros that help you do this, based on what kind of type you want to expose. Let's look at how one could expose parts of the Star Wars Schema:

#[macro_use] extern crate juniper;

use juniper::FieldResult;

enum Episode {
    NewHope,
    Empire,
    Jedi,
}

struct Human {
    id: String,
    name: String,
    appears_in: Vec<Episode>,
    home_planet: String,
}

graphql_enum!(Episode {
    Episode::NewHope => "NEW_HOPE",
    Episode::Empire => "EMPIRE",
    Episode::Jedi => "JEDI",
});

graphql_object!(Human: () |&self| {
    description: "A humanoid creature in the Star Wars universe"

    // Field resolver methods look almost like ordinary methods. The macro picks
    // up arguments and return types for the introspection schema, and verifies
    // it during compilation.
    field id() -> FieldResult<&String> {
        Ok(&self.id)
    }

    field name() -> FieldResult<&String> {
        Ok(&self.name)
    }

    field appears_in() -> FieldResult<&Vec<Episode>> {
        Ok(&self.appears_in)
    }

    field home_planet() -> FieldResult<&String> {
        Ok(&self.home_planet)
    }
});

You can find the full example in src/tests/schema.rs, including polymorphism with traits and interfaces. For an example of framework integration, see the examples folder.

Features

Juniper supports the full GraphQL query language according to the specification, including the introspective schema and all validations. It does not, however, support the schema language.

As an exception to other GraphQL libraries for other languages, Juniper builds non-null types by default. A field of type Vec<Episode> will be converted into [Episode!]!. The corresponding Rust type for e.g. [Episode] would be Option<Vec<Option<Episode>>>.

API Stability

Juniper has not reached 1.0 yet, thus some API instability should be expected.

1.0 Roadmap

Version 0.8.1 probably be re-released as 1.0 to indicate API stability.

The road to 1.0 focuses on two aspects: making sure the API hasn't got any obvious dead-ends with respect to probable future features, and improving test coverage for general execution. There are some chores that need to be completed as well.

joshmarlow/juniper

Installation

Building schemas

Features

API Stability

1.0 Roadmap