graphql-client

by graphql-rust

graphql-rust / graphql-client

Typed, correct GraphQL requests and responses in Rust

538 Stars 51 Forks Last release: over 1 year ago (0.8.0) Other 638 Commits 11 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

graphql_client

Github actions Status docs crates.io Join the chat

A typed GraphQL client library for Rust.

Features

  • Precise types for query variables and responses.
  • Supports GraphQL fragments, objects, unions, inputs, enums, custom scalars and input objects.
  • Works in the browser (WebAssembly).
  • Subscriptions support (serialization-deserialization only at the moment).
  • Copies documentation from the GraphQL schema to the generated Rust code.
  • Arbitrary derives on the generated responses.
  • Arbitrary custom scalars.
  • Supports multiple operations per query document.
  • Supports setting GraphQL fields as deprecated and having the Rust compiler check their use.
  • web client for boilerplate-free API calls from browsers.

Getting started

  • If you are not familiar with GraphQL, the official website provides a very good and comprehensive introduction.

  • Once you have written your query (most likely in something like graphiql), save it in a

    .graphql
    file in your project.
  • In order to provide precise types for a response, graphql_client needs to read the query and the schema at compile-time.

To download the schema, you have multiple options. This projects provides a CLI, however it does not matter what tool you use, the resulting

schema.json
is the same.
  • We now have everything we need to derive Rust types for our query. This is achieved through a procedural macro, as in the following snippet:
  use graphql_client::GraphQLQuery;

// The paths are relative to the directory where your Cargo.toml is located. // Both json and the GraphQL schema language are supported as sources for the schema #[derive(GraphQLQuery)] #[graphql( schema_path = "tests/unions/union_schema.graphql", query_path = "tests/unions/union_query.graphql", )] pub struct UnionQuery;

The

derive
will generate a module named
union_query
in this example - the name is the struct's name, but in snake case.

That module contains all the struct and enum definitions necessary to deserialize a response to that query.

The root type for the response is named

ResponseData
. The GraphQL response will take the form of a
Response
(the Response type is always the same).

The module also contains a struct called

Variables
representing the variables expected by the query.
  • We now need to create the complete payload that we are going to send to the server. For convenience, the GraphQLQuery trait, is implemented for the struct under derive, so a complete query body can be created this way:
  use graphql_client::{GraphQLQuery, Response};
  use std::error::Error;

#[derive(GraphQLQuery)] #[graphql( schema_path = "tests/unions/union_schema.graphql", query_path = "tests/unions/union_query.graphql", response_derives = "Debug", )] pub struct UnionQuery;

fn perform_my_query(variables: union_query::Variables) -> Result> {

  // this is the important line
  let request_body = UnionQuery::build_query(variables);

  let client = reqwest::Client::new();
  let mut res = client.post("/graphql").json(&request_body).send()?;
  let response_body: Response<:responsedata> = res.json()?;
  println!("{:#?}", response_body);
  Ok(())

} </:responsedata>

A complete example using the GitHub GraphQL API is available, as well as sample rustdoc output.

Deriving specific traits on the response

The generated response types always derive

serde::Deserialize
but you may want to print them (
Debug
), compare them (
PartialEq
) or derive any other trait on it. You can achieve this with the
response_derives
option of the
graphql
attribute. Example:
use graphql_client::GraphQLQuery;

#[derive(GraphQLQuery)] #[graphql( schema_path = "tests/unions/union_schema.graphql", query_path = "tests/unions/union_query.graphql", response_derives = "Serialize,PartialEq", )] struct UnionQuery;

Custom scalars

The generated code will reference the scalar types as defined in the server schema. This means you have to provide matching rust types in the scope of the struct under derive. It can be as simple as declarations like

type Email = String;
. This gives you complete freedom on how to treat custom scalars, as long as they can be deserialized.

Deprecations

The generated code has support for

@deprecated
field annotations. You can configure how deprecations are handled via the

deprecated
argument in the
GraphQLQuery
derive:
use graphql_client::GraphQLQuery;

#[derive(GraphQLQuery)] #[graphql( schema_path = "tests/unions/union_schema.graphql", query_path = "tests/unions/union_query.graphql", deprecated = "warn" )] pub struct UnionQuery;

Valid values are:

  • allow
    : the response struct fields are not marked as deprecated.
  • warn
    : the response struct fields are marked as
    #[deprecated]
    .
  • deny
    : The struct fields are not included in the response struct and using them is a compile error.

The default is

warn
.

Query documents with multiple operations

You can write multiple operations in one query document (one

.graphql
file). You can then select one by naming the struct you
#[derive(GraphQLQuery)]
on with the same name as one of the operations. This is neat, as it allows sharing fragments between operations.

Note that the struct and the operation in the GraphQL file must have the same name. We enforce this to make the generated code more predictable.

use graphql_client::GraphQLQuery;

#[derive(GraphQLQuery)] #[graphql( schema_path = "tests/unions/union_schema.graphql", query_path = "tests/unions/union_query.graphql", )] pub struct UnionQuery;

There is an example in the tests.

Documentation for the generated modules

You can use

cargo doc --document-private-items
to generate rustdoc documentation on the generated code.

Make cargo recompile when .graphql files have changed

There is an

include
option you can add to your

Cargo.toml
. It currently has issues however (see this issue).

Examples

See the examples directory in this repository.

Contributors

Warmest thanks to all those who contributed in any way (not only code) to this project:

  • Alex Vlasov (@indifferentalex)
  • Ben Boeckel (@mathstuf)
  • Chris Fung (@aergonaut)
  • Christian Legnitto (@LegNeato)
  • David Gräff (@davidgraeff)
  • Dirkjan Ochtman (@djc)
  • Fausto Nunez Alberro (@brainlessdeveloper)
  • Hirokazu Hata (@h-michael)
  • Peter Gundel (@peterfication)
  • Sonny Scroggin (@scrogson)
  • Sooraj Chandran (@SoorajChandran)
  • Tom Houlé (@tomhoule)

Code of conduct

Anyone who interacts with this project in any space, including but not limited to this GitHub repository, must follow our code of conduct.

License

Licensed under either of these:

  • Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
  • MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

Contributing

Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion in the work, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.