Juniper GraphQL Server Library

Juniper is a type-safe and high-performance GraphQL server library for Rust. It implements the October 2021 GraphQL specification, including support for interfaces, unions, schema introspection, and validations.

Note that Juniper builds non-null types by default. For example, a Rust field of type Vec<Episode> will be represented in GraphQL as [Episode!]!. To achieve a nullable list of nullable elements (e.g., [Episode]), you must use Option<Vec<Option<Episode>>> in your Rust code.

Juniper is a library for creating type-safe and fast GraphQL servers in Rust. It aims to provide minimal boilerplate and configuration by making schema declaration and resolution as convenient as possible within the Rust language.

Note that Juniper does not include a built-in web server; instead, it provides building blocks and pre-built integrations for existing Rust web server frameworks.

The juniper_actix crate provides integration between the juniper GraphQL implementation and the actix-web web server framework. This allows you to host GraphQL endpoints (including subscriptions) within an Actix-web application.

For detailed implementation guides and advanced usage, refer to the Juniper Book.

The juniper_axum crate provides integration between the axum web server framework and the juniper GraphQL implementation for Rust. It allows you to host GraphQL handlers within an Axum application.

For detailed guides and comprehensive examples, refer to the Juniper Book.

The N+1 problem occurs when a GraphQL resolver for a list of items (the '1' query) triggers an additional individual query for a related field for every item in that list (the 'N' queries). In Juniper, this typically happens when a field resolver on a type (e.g., Person.cult) performs its own asynchronous database lookup or HTTP request using the context, rather than batching those requests.

To resolve this in Juniper, you should use one of the following patterns:

• DataLoader: Batching and caching requests.
• Look-ahead machinery: Inspecting the selection set to perform Eager loading.

query {
  persons {
    id
    name
    cult {
      id
      name
    }
  }
}

The juniper_graphql_ws crate provides implementations for two GraphQL over WebSocket protocols. You can enable these via Cargo features:

1. graphql-transport-ws: The modern protocol used by Apollo and the graphql-ws npm package.
2. graphql-ws: The legacy protocol (formerly used by Apollo and the subscriptions-transport-ws npm package). Note that this is deprecated in favor of graphql-transport-ws.

Juniper works by mapping the GraphQL type system to Rust types. To build a GraphQL schema, you will need to implement various Juniper abstractions for different GraphQL constructs.

Key areas of the type system include:

• Objects: Defining GraphQL objects, including complex fields, context usage, error handling (field and schema errors), and generics.
• Interfaces: Implementing GraphQL interfaces.
• Unions: Implementing GraphQL unions.
• Enums: Implementing GraphQL enums.
• Input Objects: Defining types used for input arguments.
• Scalars: Defining custom scalar types.

To render the book into static HTML files, use mdbook build. The resulting files will be located in the _rendered/ directory. You can also use the Makefile shortcut from the project root.

mdbook build

# or from project root dir:
make book

To serve GraphQL subscriptions over WebSockets, use the juniper_graphql_ws crate. This crate provides implementations for both major WebSocket protocols:

1. Legacy graphql-ws protocol: Formerly used by Apollo and the subscriptions-transport-ws npm package (now being deprecated).
2. New graphql-transport-ws protocol: Provided by the graphql-ws npm package and currently used by Apollo.

Most officially supported web server framework integrations (like juniper_actix or juniper_axum) support serving schemas over WebSockets and can automatically negotiate the correct protocol based on the Sec-Websocket-Protocol HTTP header.