Quickstart

This page will give you a short introduction to the concepts in Juniper.

Once you are done here, head over to the Tutorial to learn how to use Juniper by creating a full setup step by step, or consult the other chapters for more detailed information.

Installation

Cargo.toml

[dependencies]
juniper = "0.10"

Schema example

Exposing simple enums and structs as GraphQL is just a matter of adding a custom derive attribute to them. Juniper includes support for basic Rust types that naturally map to GraphQL features, such as Option<T>, Vec<T>, Box<T>, String, f64, and i32, references, and slices.

For more advanced mappings, Juniper provides multiple macros to map your Rust types to a GraphQL schema. The most important one is the graphql_object! macro that is used for declaring an object with resolvers, which you will use for the Query and Mutation roots.

main.rs

#[macro_use] extern crate juniper;

use juniper::{FieldResult};


#[derive(GraphQLEnum)]
enum Episode {
    NewHope,
    Empire,
    Jedi,
}

#[derive(GraphQLObject)]
#[graphql(description="A humanoid creature in the Star Wars universe")]
struct Human {
    id: String,
    name: String,
    appears_in: Vec<Episode>,
    home_planet: String,
}

// There is also a custom derive for mapping GraphQL input objects.

#[derive(GraphQLInputObject)]
#[graphql(description="A humanoid creature in the Star Wars universe")]
struct NewHuman {
    name: String,
    appears_in: Vec<Episode>,
    home_planet: String,
}

// Now, we create our root Query and Mutation types with resolvers by using the
// graphql_object! macro.
// Objects can have contexts that allow accessing shared state like a database
// pool.

struct Context {
    // Use your real database pool here.
    pool: DatabasePool,
}

// To make our context usable by Juniper, we have to implement a marker trait.
impl juniper::Context for Context {}

struct Query;

graphql_object!(Query: Context |&self| {

    field apiVersion() -> &str {
        "1.0"
    }

    // Arguments to resolvers can either be simple types or input objects.
    // The executor is a special (optional) argument that allows accessing the context.
    field human(&executor, id: String) -> FieldResult<Human> {
        // Get the context from the executor.
        let context = executor.context();
        // Get a db connection.
        let connection = context.pool.get_connection()?;
        // Execute a db query.
        // Note the use of `?` to propagate errors.
        let human = connection.find_human(&id)?;
        // Return the result.
        Ok(human)
    }
});

struct Mutation;

graphql_object!(Mutation: Context |&self| {

    field createHuman(&executor, new_human: NewHuman) -> FieldResult<Human> {
        let db = executor.context().pool.get_connection()?;
        let human: Human = db.insert_human(&new_human)?;
        Ok(human)
    }
});

// A root schema consists of a query and a mutation.
// Request queries can be executed against a RootNode.
type Schema = juniper::RootNode<'static, Query, Mutation>;

fn main() {
    println!("Hello, world!");
}

We now have a very simple but functional schema for a GraphQL server!

To actually serve the schema, see the guides for our Hyper, Rocket, Warp, and Iron server integrations. Or you can invoke the executor directly:

Executor

You can invoke juniper::execute directly to run a GraphQL query:

main.rs

#[macro_use] extern crate juniper;

use juniper::{FieldResult, Variables, EmptyMutation};

#[derive(GraphQLEnum, Clone, Copy)]
enum Episode {
    NewHope,
    Empire,
    Jedi,
}

struct Query;

graphql_object!(Query: Ctx |&self| {
    field favoriteEpisode(&executor) -> FieldResult<Episode> {
        // Use the special &executor argument to fetch our fav episode.
        Ok(executor.context().0)
    }
});

// Arbitrary context data.
struct Ctx(Episode);

// A root schema consists of a query and a mutation.
// Request queries can be executed against a RootNode.
type Schema = juniper::RootNode<'static, Query, EmptyMutation<Ctx>>;

fn main() {
    // Create a context object.
    let ctx = Ctx(Episode::NewHope);

    // Run the executor.
    let (res, _errors) = juniper::execute(
        "query { favoriteEpisode }",
        None,
        &Schema::new(Query, EmptyMutation::new()),
        &Variables::new(),
        &ctx,
    ).unwrap();

    // Ensure the value matches.
    assert_eq!(
        res.as_object_value().unwrap().get_field_value("favoriteEpisode").unwrap().as_string_value().unwrap(),
        "NEW_HOPE",
    );
}

results matching ""

    No results matching ""