juniper/README.md

100 lines
3.8 KiB
Markdown
Raw Normal View History

2017-09-23 12:20:54 -05:00
<img src="https://github.com/graphql-rust/juniper/blob/master/assets/logo/juniper-dark-word.png" alt="Juniper" width="500" />
2016-09-11 11:41:29 -05:00
> GraphQL server library for Rust
[![Build Status](https://travis-ci.org/graphql-rust/juniper.svg?branch=master)](https://travis-ci.org/graphql-rust/juniper)
2017-08-07 15:12:11 -05:00
[![Build status](https://ci.appveyor.com/api/projects/status/vsrwmsh9wobxugbs?svg=true)](https://ci.appveyor.com/project/theduke/juniper/branch/master)
[![codecov](https://codecov.io/gh/graphql-rust/juniper/branch/master/graph/badge.svg)](https://codecov.io/gh/graphql-rust/juniper)
2016-10-09 09:55:18 -05:00
[![Crates.io](https://img.shields.io/crates/v/juniper.svg?maxAge=2592000)](https://crates.io/crates/juniper)
2017-07-12 04:47:54 -05:00
[![Gitter chat](https://badges.gitter.im/juniper-graphql/gitter.png)](https://gitter.im/juniper-graphql)
2016-09-11 11:48:53 -05:00
2017-06-19 02:45:58 -05:00
2016-09-11 11:41:29 -05:00
---
[GraphQL][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. We also try to make declaring and resolving
GraphQL schemas as convenient as possible as Rust will allow.
2016-09-11 11:41:29 -05:00
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][iron] and [Rocket] frameworks, including
embedded [Graphiql][graphiql] for easy debugging.
2016-09-11 11:41:29 -05:00
2016-12-05 10:06:09 -06:00
* [Cargo crate](https://crates.io/crates/juniper)
* [API Reference][docsrs]
* [Book][book]: Guides and Examples
2017-06-15 09:53:27 -05:00
## Getting Started
The best place to get started is the [Juniper Book][book], which contains
guides with plenty of examples, covering all features of Juniper.
2016-09-11 11:41:29 -05:00
To get started quickly and get a feel for Juniper, check out the
[Quickstart][book_quickstart] section.
2016-09-11 11:41:29 -05:00
For specific information about macros, types and the Juniper api, the
[API Reference][docsrs] is the best place to look.
2016-09-11 11:41:29 -05:00
You can also check out [src/tests/schema.rs][test_schema_rs] to see a complex
schema including polymorphism with traits and interfaces.
For an example of web framework integration,
see the [rocket][rocket_examples] and [iron][iron_examples] examples folders.
2016-09-11 11:41:29 -05:00
## Features
2016-09-11 11:41:29 -05:00
Juniper supports the full GraphQL query language according to the
[specification][graphql_spec], including interfaces, unions, schema
introspection, and validations.
It does not, however, support the schema language.
2016-09-11 11:41:29 -05:00
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>>>`.
2016-09-11 11:41:29 -05:00
## Integrations
2016-09-11 11:41:29 -05:00
### Data types
2016-09-11 11:41:29 -05:00
Juniper has automatic integration with some very common Rust crates to make
building schemas a breeze. The types from these crates will be usable in
your Schemas automatically.
2016-09-11 11:41:29 -05:00
* [uuid][uuid]
* [url][url]
* [chrono][chrono]
2016-09-11 11:41:29 -05:00
### Web Frameworks
2016-09-11 11:41:29 -05:00
* [rocket][rocket]
* [iron][iron]
2016-09-11 11:41:29 -05:00
## API Stability
Juniper has not reached 1.0 yet, thus some API instability should be expected.
[graphql]: http://graphql.org
[graphiql]: https://github.com/graphql/graphiql
2016-09-11 11:41:29 -05:00
[iron]: http://ironframework.io
[graphql_spec]: http://facebook.github.io/graphql
[test_schema_rs]: https://github.com/graphql-rust/juniper/blob/master/src/tests/schema.rs
2016-09-11 11:41:29 -05:00
[tokio]: https://github.com/tokio-rs/tokio
[rocket_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_rocket/examples
[iron_examples]: https://github.com/graphql-rust/juniper/tree/master/juniper_iron/examples
2017-06-15 09:53:27 -05:00
[Rocket]: https://rocket.rs
[book]: https://graphql-rust.github.io/juniper-book
[book_quickstart]: https://graphql-rust.github.io/juniper-book/quickstart.html
[docsrs]: https://docs.rs/juniper
[uuid]: https://crates.io/crates/uuid
[url]: https://crates.io/crates/url
[chrono]: https://crates.io/crates/chrono