Welcome to our Code Academy series in which we will try to present you useful tool, libraries and methods. This week we will focus on a Dgraph, a very promisng graph database.
[Dgraph](https://dgraph.io/) is an open-source distributed graph database aimed at providing high production-level scale, efficient enough to be serving real-time user queries. Dgraph uses [GraphQL](https://graphql.org/) as its default query language and responds in JSON. There has been a lot of talk in the media about Dgraph about a year ago when the company announced that it has raised [$3 million in funding](https://techcrunch.com/2017/12/19/dgraph-raises-3m-for-its-open-source-distributed-graph-database-hits-1-0-release/).

### Dgraph

Dgraph is a distributed, highly available graph database. Unlike GraphQL,  there is no concept of complex types or groups of properties. Dgraph defines the schema for properties within the graph, so you can store any GraphQL schema in Dgraph.

Dgraph cluster consists of three different nodes, each serving a different purpose:

* Dgraph Zero -  responsible for the Dgraph cluster; it assigns servers to a group, balances data between them (required)
* Dgraph Alpha - responsible for predicates and indexes (required)
* Dgraph Ratel - serves the UI to run queries, mutations & schema alterations.

### Starting with DgraphQL

If you want to give it a try the easiest way to do it is to use Docker (you will need also [Docker Compose](https://docs.docker.com/compose/install/)).

```bash
docker pull dgraph/dgraph
```

Once you have Docker Compose installed to start up Dgraph put below code in your docker-compose yaml file.

```ts
version: "3.2"
services:
zero:
 image: "dgraph/dgraph:latest"
 volumes:
   - type: volume
     source: dgraph
     target: /dgraph
     volume:
       nocopy: true
 ports:
   - 5080:5080
   - 6080:6080
 restart: on-failure
 command: dgraph zero --my=zero:5080
server:
 image: "dgraph/dgraph:latest"
 volumes:
   - type: volume
     source: dgraph
     target: /dgraph
     volume:
       nocopy: true
 ports:
   - 8080:8080
   - 9080:9080
 restart: on-failure
 command: dgraph alpha --my=server:7080 --lru_mb=2048 --zero=zero:5080
ratel:
 image: "dgraph/dgraph:latest"
 volumes:
   - type: volume
     source: dgraph
     target: /dgraph
     volume:
       nocopy: true
 ports:
   - 8000:8000
 command: dgraph-ratel

volumes:
dgraph:

```

Let's take A Song of Ice and Fire (aka. Game of Thrones) books series as our data set:

```bash
curl localhost:8080/mutate -H "X-Dgraph-CommitNow: true" -XPOST -d $'
{
set {
 _:ned <name> "Eddard Stark" .
 _:robert <name> "Robbert Baratheon" .
 _:cersei <name> "Cersei Lannister" .
 _:joffrey <name> "Joffrey Baratheon".

 _:got1 <name> "A Song of Ice and Fire: A Game of Thrones" .
 _:got1 <release_date> "1996-08-01" .
 _:got1 <characters> _:ned .
 _:got1 <characters> _:robert .
 _:got1 <characters> _:cersei .
 _:got1 <characters> _:joffrey .

 _:got2 <name> "A Song of Ice and Fire:A Clash of Kings" .
 _:got2 <release_date> "1998-11-16" .
 _:got2 <characters> _:cersei .
 _:got2 <characters> _:joffrey .


 _:got3 <name> "A Song of Ice and Fire: A Storm of Swords" .
 _:got3 <release_date> "2000-08-08" .
 _:got3 <characters> _:cersei .
 _:got3 <characters> _:joffrey .
  }
}
' | python -m json.tool | less

```

You can alter your schema by adding indexes on some of data. This will allow queries to very convenient features as term matching, filtering and sorting:

```bash
curl localhost:8080/alter -XPOST -d $'
name: string @index(term) .
release_date: date @index(year) .
' | python -m json.tool | less
```

Having that done you can either query for all the books:

```bash
curl localhost:8080/query -XPOST -d $'
{
me(func: has(characters)) {
 name
}
}
' | python -m json.tool | less
```

or query for just those published after year 2000:

```bash
curl localhost:8080/query -XPOST -d $'
{
me(func:allofterms(name, " A Song of Ice and Fire")) @filter(ge(release_date, "2000")) {
  name
  release_date
  characters {
   name
  }
}
}
' | python -m json.tool | less
```

which will result in:

```json
{
"data":{
  "me":[
    {
      "name":"A Song of Ice and Fire: A Storm of Swords",
      "release_date":"2000-08-08",
      "characters":[
        {
          "name":"Cersei Lannister"
        },
        {
          "name":"Joffrey Baratheon"
        },
      ]
    },
  ]
}
}
```

And that's it! Thanks to Mr. Dgraph Ratel we have a filtered data we have queried for.

![Dgraph](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/media/dgraph.webp)
Source: [https://dgraph.io/](https://dgraph.io/)

Code Academy - Dgraph a distributed graph database you need to know

An important part of any development project is handling errors as any application, no matter how simple it is, may contain a considerable amount of errors. In our previous blog posts, we have made a comparison of certain aspects ([data fetching](https://graphqleditor.com/blog/graphql-vs-rest/), [performance](https://graphqleditor.com/blog/graphql-vs-rest-performance/), [caching](https://graphqleditor.com/blog/graphql-vs-rest-caching/)) of [GraphQL](https://github.com/graphql) vs REST so you already know that it differs a lot. The same is true also in terms of handling errors.

## Handling errors in REST

Error handling in REST is pretty straightforward, we simply check the [HTTP](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) headers to see the status of a response:

* `200 OK`,
* `404 Not Found`,
* `500 Internal Server Error`

and so on.

Depending on the HTTP status code we get, we can easily identify what’s went wrong and how to handle it. In [GraphQL](https://graphql.org/) it’s different.

![](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/media/405-1730821717940.webp)

## Errors in GraphQL

There are plenty of errors that a client can face when querying a GraphQL Server. Regardless of whether it's a query, mutation or subscription, they can be divided into six types:

* Server problems (5xx HTTP codes, 1xxx WebSocket codes)
* Client problems like rate-limited, unauthorized, etc. (4xx HTTP codes)
* `Query` is missing or was malformed
* `Query` fails GraphQL internal validation of syntax, schema logic etc.
* User-provided `variables` or `context` is bad and `resolve`/`subscribe` function shows an error
* Developer error occurred inside the `resolve`/`subscribe` function

The first four are critical errors that ignore all data. The first three happens before we call GraphQL server, the fourth one calls GraphQL receiving only 'errors' in response.

On the contrary, the GraphQL server will always return `200 OK` for position five and six (if operated over HTTP). If there is an error while processing GraphQL queries, the detailed error message is sent to the customer with the answer i.e.

```gql
    {
      "errors": [
        {
          "message": "Field \"blabla\" must not have a selection since type \"String\" has no subfields.",
          "locations": [
            {
              "line": 2,
              "column": 20
            }
          ]
        }
      ]
    }
```

So how to handle this type of errors? GraphQL is a very immature language so some parts (such as handling errors) do not have worked out the best practices, but there are some approaches that we highly recommend to follow:

#### 1. DATA IS DATA

If GraphQL returns `results.data`, there is no error.

#### 2. ERRORS AS A PART OF SCHEMA

If the viewer should see the error, make sure to return the error as a field in your response. If your server expect an error it shouldn't interup the resolution, instead return a regular payload with `error` field explainng what went wrong.

```gql
    return {
        error:{
            id:'222'
            type:'errorType'
            title: 'Name of an error'
            message: 'Let user know what's wrong how to fix'
        }
    }
```

GraphQL vs REST - Handling errors

GraphQL is a query language for APIs that was originally built by Facebook.
Its biggest advantage is making a lot easier to get the data you actually need from a query. Today we will show you how to set up MongoDB with GraphQL.

## Install MongoDB with Homebrew

First you need to install a Homebrew. To do it go to Visual Code Studio and run this line from Brew.sh:

```bash
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```

Now you should have your Homebrew installed. If you had it already installed, we suggest to do a brew update before proceeding, then you can install MongoDB:

```bash
$ brew update
$ brew install mongo
```

What you need to do now is to go to a root directory, create the directory for the database and set its permissions, then you can star Mongo:

```bash
$ sudo mkdir -p /data/db
$ sudo chmod 777 /data/db
$ mongod
```

Et voila! We have it installed and running.

## Mongoose

[Mongoose](https://mongoosejs.com/) provides a straight-forward, schema-based solution to model your application data.
It includes:

* built-in type casting,
* validation,
* query building,
* business logic hooks

So let's install Mongoos. Make sure you are in the right directory and use `$npm install`:

```bash
$ npm install --save mongoose
```

## Connecting Mongo

Create a new folder and move your `resolvers.js` and `schema.js` files there. Remember to update your `index.js` file to make sure everything will be correctly imported here. Once we have it done we can create a new file in our fresh folder which we will use to connect Mongo to our databases, let's call it `connect.js`.

```ts
import mongoose from 'mongoose';

mongoose.Promise = global.Promise;
mongoose.connect =('mongodb://localhost/users', {
    useMongoClient: true
});
```

When we have it done we can start creating our schema for Mongo with the same elements as our original schema.

```ts
const usersSchema = new mongoose.Schema({
    name: 
        type: String
    }
})
```

The next important step is to create a value to our variable with that model inside, passing the schema and export:

```ts
const Users = mongoose.model('users', usersSchema)
export {Users};
```

Now let's create some GraphQL resolvers. So let's go to `resolvers.js` and start with importing Mongoose and Users into resolvers:

```ts
import mongoose from 'mongoose';
import { Users } from './connect';

export const resolvers ={
    Query: {
        getUser: ({id}) => {
            return new User (id, userDatabase[id]);
        },
    },
    Mutation: {
        createUser: (root, { input}) => {
            const newUser = new Users({
                name: input.name,
            });

            newUser.id = newUser._id;

            return new Promise((resolve, object)) =>
                newUser.save((err) => {
                    if (err) reject (err)
                    else resolve(newUser)
                })
            })    
        },
    },
};
```

In next part we will create nodejs GraphQL server. Stay tuned!

![Done!](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/blogpost/done-1730844481950.webp)

Installing MongoDB for GraphQL

Let's explore the next stage of our [GraphQL](https://graphqleditor.com/) tutorial -  type system and how it defines what data can be queried. Since GraphQL can be used with any backend programming language, we'll focus mostly on general the concepts.

## Type language

GraphQL can be used with any language. Since we can't rely on any specific language syntax, to talk about GraphQL schemas, we'll define our simple language. We'll use the "GraphQL schema language" - it's similar to the query and allows us to talk about GraphQL schemas in an agnostic way

## Type system

GraphQL query language is basically about selecting fields on objects. Let's check that on our example:

```gql
{
  Actor {
    name
    appearsIn
  }
}
```

```gql
{
  "data": {
    "hero": {
      "name": "Arnold",
      "appearsIn": [
        "TERMINATOR",
        "CONAN",
        "PREDATOR"
      ]
    }
  }
}
```

1. We start with a unique "root" object and select actor field on that
2. For the object returned by actor, we select the name and appearsIn fields

GraphQL query closely matches the result; therefore you can predict what the query will respond without knowing much about the server. But it's helpful to have an accurate description of the data we can ask for - what fields can we choose? What fields are possible on those sub-objects? What kinds of things might they respond?

Every GraphQL service describes a set of types which ultimately represent the set of potential data you can query on that service. Then, when queries come in, they are validated and executed against that schema.

## Object types and fields

The essential elements of a GraphQL schema are object types, which describe a kind of object you can fetch from your service, and what fields it has. In the GraphQL schema language, we might represent it like this:

```ts
type Actor {
  name: String!
  appearsIn: [Movie!]!
}
```

The language is pretty simple, but let's go over it so that we can have a shared dictionary:

1. Actor is a GraphQL Object Type, meaning it's a type with some fields. Most of the types in your schema will be object types.
2. name and appearsIn are fields on the Actor type. That means that name and appearsIn are the only fields that can appear in any part of a GraphQL query that operates on the Actor type.
3. String is one of the built-in scalar types - these are types that resolve to a single scalar object, and can't have sub-selections in the query. We'll go over scalar types later.
4. String! means that the field is non-nullable, saying that the GraphQL service promises always to give you value when you ask. In the type of language, we'll serve those with an exclamation mark.
5. \[Movie!]! represents an collection of Movie objects. Since it is also non-nullable, you can regularly expect an array (with zero or more items) when you ask the appearsIn field. And since Movie! is also non-nullable, you can always expect every item of the array to be an Movie object.
   Now you know what a GraphQL object type looks like, and how to read the basics of the GraphQL.

## The Query and Mutation types

Most types in your schema will be standard object types, but two types are special within a schema:

```ts
schema {
  query: Query
  mutation: Mutation
}
```

Every GraphQL service has a query type and don't need to have a mutation type. These types are the same as a regular object type, but they are unique because they define the entry point of every GraphQL query.

```ts
query {
  hero {
    name
  }
  droid(id: "2000") {
    name
  }
}
```

```ts
{
  "data": {
    "hero": {
      "name": "R2-D2"
    },
    "droid": {
      "name": "C-3PO"
    }
  }
}
```

That means that the GraphQL service needs to have a Query type with hero and droid fields:

```ts
type Query {
  hero(episode: Episode): Character
  droid(id: ID!): Droid
}
```

Mutations work similarly - you define fields on the Mutation type, and those are possible as the root mutation fields you can call in your query.

It's essential to master that other than the special status of being the "entry point" into the schema, the Query and Mutation types are the same as any other GraphQL object type, and their fields act precisely the same way.

## Scalar types

A GraphQL object type has a name and fields, but at some level those fields have to resolve to some particular data. That's where the scalar types come in: they represent the leaves of the query.

In the next query, the name and appearsIn fields will choose to scalar types. We know this because those fields don't have any sub-fields - they are the leaves of the query.

```gql
{
  Actor {
    name
    appearsIn
  }
}
```

```gql
{
  "data": {
    "hero": {
      "name": "Arnold",
      "appearsIn": [
        "TERMINATOR",
        "CONAN",
        "PREDATOR"
      ]
    }
  }
}
```

GraphQL comes with a set of default scalar types out of the box:

* Int: A signed 32‐bit integer.
* Float: A signed double-precision floating-point value.
* String: A UTF‐8 character sequence.
* Boolean: true or false.
* ID: The ID scalar type represents a unique identifier, often used to refetch an object or as the key for a cache. The ID type is serialized in the same way as a String; however, defining it as an ID signifies that it is not intended to be human‐readable.

In most GraphQL service implementations, there is also a way to specify custom scalar types. For example, we could define a Date type:

```ts
scalar Date
```

Then it's up to our implementation to define how that type should be validated serialized or deserialized. For example, you could specify that the Date type should always be serialized into an integer timestamp, and your client should know to expect that format for any date fields.

## Enumeration types

Also called Enums, enumeration types are a special kind of scalar that's limited to an appropriate set of allowed values. This allows you to:

Validate that any arguments of this type are one of the allowed values
Communicate through the type system that a field will always be one of a finite set of values

```ts
enum Movie {
  TERMINATOR
  CONAN
  PREDATOR
}
```

It means that anywhere we use the type Movie in our schema, we expect it to be precisely one of TERMINATOR, CONAN, or PREDATOR.

Note that GraphQL service implementations in different languages will have their own programming-specific way to deal with enums. In languages that support enums as a first-class citizen, the application might take advantage of that; in a language like JavaScript with no enum support, these values might be internally mapped to a set of integers.

GraphQL Tutorial - Schemas and Types Part 1


[GraphQL](https://graphql.org/) is a query language for [API](https://en.wikipedia.org/wiki/Application_programming_interface)s that:
provides a complete and understandable description of the data in your API,
allows Clients to ask specifically for what they need,
makes evolving APIs over time a lot easier,
enhance your APIs with amazing tools inaccessible with REST

GraphQL differs from traditional RESTful APIs (we covered that shortly in our [GraphQL vs REST](https://graphqleditor.com/blog/graphql-vs-rest/) blog post) so on your first encounter with the GraphQL you might notice a lot of unfamiliar terms and phrases. As big GraphQL fans, we decided to prepare a sort of GraphQL Dictionary containing the most common GraphQL terms to help you start with GraphQL.

![I know the best words](/bestwords.webp)

## Argument
Argument is a set of key-value attached to a field. The Arguments can have a form of literal values or variables.

## Alias
Alias is an alternative name assigned to the result of a field to avoid conflicts during data fetching operations i.e. `admin` and `regular`.

```gql
{
 admin: users(role: admin) {
   id
   firstname
   lastname
 }
 regular: users(role: regular) {
   id
   firstname
   lastname
 }
}
```

## Directive
An explanation preceded by a `@` that encloses the logic for query execution on client/server. GraphQL built-in directives are @skip and @include, and allow to define custom ones.

## Field
A basic unit of data you request from your schema returned as a field in JSON response i.e. `id`and `name`.

```gql
type User {
 id: Int!
 name: String
}
```

## Fragment
A selection set that can be reused in multiple query operations. A GraphQL fragment is a shared piece of query logic.

## GraphQL Editor
GraphQL Editor makes understanding GraphQL schema a lot easier. Plan your schema by linking visual blocks and GraphQL Editor will transform them into code.

![GraphQL Editor](/graph.webp)

## Introspection
A method to provide precise information about the schema of a GraphQL API. Introspections are prefixed by "__".

## Mutation
One of basic GraphQL operation allowing to manipulate data (create, modify, delete).

```gql
mutation DeleteTodo($type: String!) {
 deleteTodo(type: $type) {
   id
   type
 }
}
```

## Object Type
It's type in a GraphQL schema that contains fields. `User` is our Object Type here:
```gql
type User {
  name: String!,
}
```

## Operation
The single query, mutation or subscription, which could be interpreted by execution engine in GraphQL.

## Operation Name
A name for above-mentioned elements. Name make a lot easier identifying, logging or debugging errors in a GraphQL server.

## Query
It's a basic fetch operation to reqest data in GraphQL.

## Query Colocation
One of [GraphQL best practices](https://graphql.org/learn/best-practices/), where you place a GraphQL query in the same location as the app component’s view logic.

## Query whitelisting
A security practice involving defining a list of approved queries that are allowed in your app.

## Resolver
A function tconecting your GraphQL schema elements to backends.  Resolvers turn operations into data; they can return strings, ints, null & other primitives.


## Schema
A GraphQL schema is the central piece of every GraphQL server implementation. The GraphQL schema is responsible for the whole logic of your project and describes functionalities available to the client app.

## Schema Definition Language (SDL)
A GraphQL Schema Definition is a way to define a GraphQL schema. The syntax is a are part of the official GraphQL specification. The main components of each schema are the `types` and their `fields`.

The GraphQL schema for a movie review site could be defined like this:

```gql
type Review {
 id: String!
 title: String!
 publishedAt: DateTime!
 stars: Int! @default(value: 0)
 feed: Feed @relation(name: "Reviews")
}

type Feed {
 id: String!
 name: String!
 description: String,
 reviews: [Review!]! @relation(name: "Review")
}
```

## Schema Stitching
Merging minor schemas into central GraphQL schema.

## Subscription
Is a real-time operation in GraphQL that is defined in a schema.

```gql
type Subscription {
 reviewAdded(repoFullName: String!): Review
}
...graphql
subscription onReviewAdded($repoFullName: String!){
 reviewAdded(repoFullName: $repoFullName){
   id
   content
 }
}
```

## Scalar Type
It's [GraphQL type](/docs/what-is-graphql/) that validate the data that GraphQL field resolves. String, Int, Boolean, Float are all built-in scalars that you can do a lot with out of the box. Custom scalar types can be specified in a GraphQL service implementation.


## Type System
It's a set of rules that define the set of data that can be valiudated, queried & executed.

## Variable
It's a value that can be passed to an operation, like `userID` in below example:

```gql
query GetUser($userId: ID!){
 user(id: $userId){
   name
 }
}
```








GraphQL Tutorial - Dictionary

[GraphQL](https://graphql.org/) is a query language for [API](https://en.wikipedia.org/wiki/Application_programming_interface)s that:
provides a complete and understandable description of the data in your API,
allows Clients to ask specifically for what they need,
makes evolving APIs over time a lot easier,
enhance your APIs with amazing tools inaccessible with REST

GraphQL differs from traditional RESTful APIs (we covered that shortly in our [GraphQL vs REST](https://graphqleditor.com/blog/graphql-vs-rest/) blog post) so on your first encounter with the GraphQL you might notice a lot of unfamiliar terms and phrases. As big GraphQL fans, we decided to prepare a sort of GraphQL Dictionary containing the most common GraphQL terms to help you start with GraphQL.

![I know the best words](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/blogpost/bestwords.webp)

## Argument

Argument is a set of key-value attached to a field. The Arguments can have a form of literal values or variables.

## Alias

Alias is an alternative name assigned to the result of a field to avoid conflicts during data fetching operations i.e. `admin` and `regular`.

```gql
{
 admin: users(role: admin) {
   id
   firstname
   lastname
 }
 regular: users(role: regular) {
   id
   firstname
   lastname
 }
}
```

## Directive

An explanation preceded by a `@` that encloses the logic for query execution on client/server. GraphQL built-in directives are @skip and @include, and allow to define custom ones.

## Field

A basic unit of data you request from your schema returned as a field in JSON response i.e. `id`and `name`.

```gql
type User {
 id: Int!
 name: String
}
```

## Fragment

A selection set that can be reused in multiple query operations. A GraphQL fragment is a shared piece of query logic.

## GraphQL Editor

GraphQL Editor makes understanding GraphQL schema a lot easier. Plan your schema by linking visual blocks and GraphQL Editor will transform them into code.

![GraphQL Editor](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/blogpost/graph.webp)

## Introspection

A method to provide precise information about the schema of a GraphQL API. Introspections are prefixed by "\_\_".

## Mutation

One of basic GraphQL operation allowing to manipulate data (create, modify, delete).

```gql
mutation DeleteTodo($type: String!) {
 deleteTodo(type: $type) {
   id
   type
 }
}
```

## Object Type

It's type in a GraphQL schema that contains fields. `User` is our Object Type here:

```gql
type User {
  name: String!,
}
```

## Operation

The single query, mutation or subscription, which could be interpreted by execution engine in GraphQL.

## Operation Name

A name for above-mentioned elements. Name make a lot easier identifying, logging or debugging errors in a GraphQL server.

## Query

It's a basic fetch operation to reqest data in GraphQL.

## Query Colocation

One of [GraphQL best practices](https://graphql.org/learn/best-practices/), where you place a GraphQL query in the same location as the app component’s view logic.

## Query whitelisting

A security practice involving defining a list of approved queries that are allowed in your app.

## Resolver

A function tconecting your GraphQL schema elements to backends.  Resolvers turn operations into data; they can return strings, ints, null & other primitives.

## Schema

A GraphQL schema is the central piece of every GraphQL server implementation. The GraphQL schema is responsible for the whole logic of your project and describes functionalities available to the client app.

## Schema Definition Language (SDL)

A GraphQL Schema Definition is a way to define a GraphQL schema. The syntax is a are part of the official GraphQL specification. The main components of each schema are the `types` and their `fields`.

The GraphQL schema for a movie review site could be defined like this:

```gql
type Review {
 id: String!
 title: String!
 publishedAt: DateTime!
 stars: Int! @default(value: 0)
 feed: Feed @relation(name: "Reviews")
}

type Feed {
 id: String!
 name: String!
 description: String,
 reviews: [Review!]! @relation(name: "Review")
}
```

## Schema Stitching

Merging minor schemas into central GraphQL schema.

## Subscription

Is a real-time operation in GraphQL that is defined in a schema.

```gql
type Subscription {
 reviewAdded(repoFullName: String!): Review
}
...graphql
subscription onReviewAdded($repoFullName: String!){
 reviewAdded(repoFullName: $repoFullName){
   id
   content
 }
}
```

## Scalar Type

It's [GraphQL type](/docs/what-is-graphql/) that validate the data that GraphQL field resolves. String, Int, Boolean, Float are all built-in scalars that you can do a lot with out of the box. Custom scalar types can be specified in a GraphQL service implementation.

## Type System

It's a set of rules that define the set of data that can be valiudated, queried & executed.

## Variable

It's a value that can be passed to an operation, like `userID` in below example:

```gql
query GetUser($userId: ID!){
 user(id: $userId){
   name
 }
}
```

In this GraphQL tutorial, we will show you how easy is implementing GraphQL in a React application. We’ll be using the [React Apollo](https://github.com/apollographql/react-apollo) library that allows you to fetch data from your GraphQL server and use it the [React](https://react.dev/) framework.

## Setup a project

Before you start make sure that you have Node.js installed. To get started we first need to set up a new React project. The easiest way to do so is to use [create-react-app](https://github.com/facebook/create-react-app), which allows you to create a new React project with zero build configuration.

```bash
$ npx create-react-app my-graphql-project
$ cd my-graphql-project
$ npm start
```

## Install dependencies

Once you have above done the next step will be to install dependencies. You can do it with a single NPM command which will install the following packages:

```bash
$ npm install apollo-boost react-apollo graphql graphql-tag
```

- `apollo-boost`: a package with all necessary Apollo Client components
- `react-apollo`: a view layer for React
- `graphql` & `graphql-tag`: both required to parse GraphQL queries

## Create a client

Now you need to create an instance of [Apollo Client](https://github.com/apollographql/apollo-client). You can do it `App.js` by adding the following code:

```ts
import ApolloClient from 'apollo-boost'
const client = new ApolloClient({
  uri: '[Put your GraphQL endpoint URI here]',
})
```

## Create GraphlQL Endpoint

To start with, all you really need is the endpoint for your GraphQL server. You can define it in `uri` or it will be `/graphql` endpoint on the same host as your app by default.

## Connect your React app with Apollo

To connect the Apollo Client to React use the `ApolloProvider` component exported from `react-apollo`. The `ApolloProvider` works simillar to React’s context provider:

- it wrapps your React app,
- places the client on the context,

giving you access to it anywhere in your component tree.

```ts
import React from 'react'
import { render } from 'react-dom'
import { ApolloProvider } from 'react-apollo'
import ApolloClient from 'apollo-boost'
const client = new ApolloClient({
  uri: '[Put your GraphQL endpoint URI here]',
})
const App = () => (
  <ApolloProvider client={client}>
    <div>
      <h1>My app</h1>
    </div>
  </ApolloProvider>
)

render(<App />, document.getElementById('root'))
```

## You made it!

Now, once your first React + GraphQL app is up and running you can start fetching some data with GraphlQL Queries have fun!

Getting started with React GraphQL

## Graphs, graphs everywhere!

Graphs are powerful tools for modeling complicated structures. In [GraphQL](https://graphql.org/) you model your business model as a graph by defining a schema, then within your [GraphQL schema](https://graphql.org/learn/schema/), you define different types of nodes and how they relate with other nodes. This creates a well-known pattern (Object-Oriented Programming) on the client side. Think of your [GraphQL schema](https://the-guild.dev/graphql/tools/docs/introduction) as a common language spoken by your business team, development team as well as your users. Defining your schema is a crucial thing for the GraphQL project. Since GraphQL only defines the interface you have the freedom to use it with any backend.

There are plenty of tools and extensions helping with its creation, among them our [Visual GraphQL Editor](https://graphqleditor.com/).

![](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/media/graphs.webp)

## Authorization

Authorization is a type of business logic that describes whether a given user, session or context has permission to perform some action or read data. Defining authorization logic inside the resolver is fine when prototyping, however, you should delegate authorization logic to the business logic layer for production. It's recommended having a single source of truth for authorization instead of a token or API key, this allows better handling of authorization and authentication in different stages of the request processing pipeline.

## Caching

Caching is an integral part of the HTTP specification. Because of the way GraphQL operates, it does not follow the HTTP specification for caching and instead uses a single endpoint, so it is up to the developer to make sure that caching is implemented properly for non-mutable queries. Fortunately, there are some libraries that can help GraphQL solve this problem like [Apollo](https://www.apollographql.com/) or [FlacheQL](https://github.com/FlacheQL/FlacheQL). You can read more about them in [GraphQL vs REST - Caching](https://graphqleditor.com/blog/graphql-vs-rest-caching/) blog post.

![](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/media/cache.webp)

## Pagination

A common practice in GraphQL is to trace the interactions between sets of objects. There are many ways in which these dependencies can be disclosed. In GraphQL we could do pagination as:

* `friends(first:2 offset:2)` to ask for the next two on the list.
* `friends(first:2 after:$friendId)`, to ask for the next two after the last friend we fetched.
* `friends(first:2 after:$friendCursor)`, where we get a cursor from the last item and use that to paginate.

Different pagination models enable different client capabilities

GraphQL Best Practices

As you all know, a cache is a hardware or software component that stores data (usually as a result of an earlier computation) so that future requests could be served faster. Caching is considered by many developers as one of the GraphQL weaknesses. Is that true? And why caching is so important?

## The importance of caching

We implement caching to increase the performance of our applications and decrease loads on our servers. Google observed that 53% of page visitors leave the page if it takes more than three seconds to load. A neural network trained to predict user behavior with 90% accuracy revealed that as page load time goes from one second to five, the probability of bounce increases by 90%.

![](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/media/google-1730821621741.webp)

## GraphQL vs REST

Caching is an integral part of the HTTP specification that REST APIs can use. GET vs. POST caching semantics is clearly defined so that browser caches, intermediary proxies, and server frameworks can follow. Because of the way GraphQL operates, it does not follow the HTTP specification for caching and instead uses a single endpoint, so it is up to the developer to make sure that caching is implemented properly for non-mutable queries. The GraphQL page even frankly suggests that the client should take care of the caching on its end. Fortunately, there are some libraries that can help GraphQL solve this problem with the help of developers.

## GraphQL Libraries that can help

Choosing one of them will help you develop more performance-focused applications and reduce the number of sessions being bounced:

* [FlacheQL](https://github.com/FlacheQL/FlacheQL) - FlacheQL offers partial retrieval of cached data based on search parameters — a feature that no other [GraphQL](https://graphql.org) library offers. Larger implementations like Apollo and Relay can only cache data based on GraphQL query fields.
* [Apollo GraphQL](https://www.apollographql.com) - Apollo includes a default cache implementation for Apollo Client 2.0. It's called InMemoryCache and it is a normalized data storage that supports all of Apollo Client 1.0’s features without the dependency on Redux. You can read more about its use-cases [here](https://www.apollographql.com/docs/react/caching/cache-configuration/).
* [Relay Library](https://github.com/graphql/graphql-relay-js) - [Relay](https://relay.dev/) faciliate creation of Relay-compliant servers using the GraphQL.js reference implementation of a GraphQL server.

## Conclusion

GraphQL definitely needs a better caching system to win the GraphQL vs REST war.

GraphQL vs REST - Caching


In [Part 1](https://graphqleditor.com/blog/graphql-tutorial-queries-and-mutations-part1/) of our GraphQL Tutorial, we have ended covering Operation Name. Let’s move to a feature allowing us to save some time as well as bits over the wire - the Variables.

## Variables

Until now, our arguments were written inside a query string. As most of the time, arguments to fields will be dynamic, it’s a poor idea to pass the dynamic arguments in the query string. To handle this client-side code would need to manipulate the query string at runtime dynamically, serializing it into a format specific for GraphQL. [GraphQL](https://graphqleditor.com/) comes with a solution - variables.

To start using them, we need to follow three steps. First, we need to replace a static value in the query with $variableName. Next to declare $variableName as one of the variables accepted by the query and finally pass variableName: value in the separate, transport-specific variables dictionary (a JSON would be just fine).

Query:
```gql
query UserNameAndFriends($gender: Gender) {
  user(gender: $gender) {
    name
    friends {
      name
    }
  }
}
```

Variable:
```gql
{
  "gender": "MALE"
}
```

Result:

```ts
{
  "data": {
    "user": {
      "name": "James",
      "friends": [
        {
          "name": "Adam"
        },
        {
          "name": "Paul"
        },
        {
          "name": "Chris"
        }
      ]
    }
  }
}
```

## Variable definitions

The variable definitions are the part that looks like this in the above query ($gender: Gender). It operates the same way as the argument definitions for a function in a typed language. It lists all variables prefixed with $ followed by their type (in this case Gender).

All declared variables must be both:
- Scalars
- Enums
- Input Object Types

This means that if you want to pass a complex object into a field, you need to know which input type will match on the server. 

Variable definitions can be:
- optional 
- requisitely

In the above case, it is optional. But if the field in which you pass the variable requires a non-zero argument, the variable must also be required.

You will learn more about the syntax for these variable definitions in our next article about the schema language GraphQL.

## Default variables

In [GraphQL](https://graphql.org/) you can assign Default values to the variables. It’s done by by adding the default value after the type declaration in your query. If Default values are provided for all variables, you can call the query without passing any variables. Note that If you will pass any variables in your query they Default values will be overridden.

```gql
query UserNameAndFriends($gender: Gender = MALE) {
  user(gender: $gender) {
    name
    friends {
      name
    }
  }
}
```
## Directives

Directives let you include or exclude a field if a variable is `true` or `false`. It's very useful when we need to dynamically change the structure of the query.

Query:
```gql
query User($gender: Gender, $withFriends: Boolean!) {
  user(gender: $gender) {
    name                
    friends @include(if: $withFriends) {
      name
    }
  }
}
```

Variables:
```gql
{
  "gender": "MALE",
  "withFriends": true
}
```
Result:
```ts
{
  "data": {
    "user": {
      "name": "James",
      "friends": [
        {
          "name": "Adam"
        },
        {
          "name": "Paul"
        },
        {
          "name": "Chris"
        }
      ]
    }
  }
}
```

In this case `withFriends` variable we pass is `true` so we also get the friends field, if `false` we won't.

There are two types of directives available in GraphQL:
- `@include(if: Boolean)` that includes field in the result if true.
- `@skip(if: Boolean)` that skip field if the argument is true.

As already mentioned, Directives are great to handle situations where you normally would have to perform string manipulations to change some fields in your query. 



GraphQL Tutorial - Queries and mutations Part 2


This time let’s take a look at another important aspect of [GraphQL](https://graphqleditor.com/) vs REST discussion - the PERFORMANCE.


## GraphQL = performance vs REST = reliability 

The main GraphQL quality is being less loquacious than traditional [REST API](https://www.restapitutorial.com/lessons/whatisrest.html).  GraphQL treats performance as its top priority while REST is focused on keeping services reliability as their main objective. Even if a REST API returns only a basic partial, it is still transferring more data, while GraphQL is always aiming for the smallest possible request. In an example, if the client needs a field, they request it, and if the API adds a new field, clients don't get it, unless it's being added into the GraphQL query.


## No wasted bits over the wire

You all have seen APIs where you need to `GET /author` first and then fetch each book individually via `GET /author/:id/books/:id` endpoint. This result in n+1 queries, a  well-known performance issue face in REST APIs.  While REST API calls are chained on the client side before the final representation can be formed for display, in GraphQL its simplified by enabling the server to combined all the data for the client within a single query which results in less bits being transferred over the wire.

```gql
{
  author (id: "1") {
    name
    book (id: "5") {
      title
    }
  }
}
```
```ts
{
  "data": {
    "author: {
      "name": "George R.R. Martin",
      "book": [
        {
          "title": "A Dance with Dragons"
        }
      ]
    }
  }
}
```

## Conclusion

[GraphQL](https://graphql.org/) is faster than [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) because as you can pick the fields you want to query, so the request will always be the smallest possible. Additionally, with GraphQL, you can enquire multiple entities in one request,  and because less bits will be transferred over the wire so your projects will perform faster than while using [REST](https://en.wikipedia.org/wiki/Representational_state_transfer).





GraphQL vs REST Performance

GraphQL is a query language for APIs and a runtime for fulfilling these queries with your existing data. The technology makes it possible for clients to request data that they exactly need, nothing more. GraphQL queries not only have access to the properties of a single source but also easily track references between them. While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data your app needs in a single request, making applications using GraphQL a lot faster, even on mobile network connections.

As you already know [npm Inc.](https://www.npmjs.com/) claims that the [GraphQL is going to be a tech force to reckon in 2019](https://graphqleditor.com/blog/javascript-predictions-for-2019-by-npm/). There is no better way to start your journey with GraphQL than use the most popular client library which is [Apollo GraphQL](https://www.apollographql.com/).

## What’s Apollo GraphQL?

Apollo is an implementation of GraphQL created to address the specific needs of modern development teams building data-driven applications. It adopts an agile, scalable approach that takes extra care not to modify existing APIs and services. The library puts an emphasis on tooling and workflows. The Apollo GraphQL platform is a stack of open source components, commercial extensions, and cloud services.

![structure.webp](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/blogpost/structure.webp)

Source: [Apollo Docs](https://www.apollographql.com/docs/)

## Most of the core components are open source

Apollo is an open source company, focused on what developers really need, and with a clear mission which is providing a better GraphQL experience for everyone. The collaboration of hundreds of developers working on Apollo Client, Apollo Server, as well as other components of the Apollo platform, makes it an industry-leading solution for GraphQL implementations.

Source: [Apollo](https://www.apollographql.com/)

[Apollo Server](https://github.com/apollographql/apollo-server) is a JavaScript GraphQL server for defining a schema and a set of resolvers that implement each part of that schema. An Apollo Server is extensible which means plugins can hook into each stage of the request pipeline. This is a great feature that allows implementing custom behaviors as add-on packages. Apollo Server works with any GraphQL schema built with GraphQL.js, serverless environments such as AWS Lambda and is open source and community-maintained.

[Apollo Client](https://github.com/apollographql/apollo-client) is a full-featured GraphQL client that manages data and state in your app. It enables a declarative programming style that allows developers to define queries as part of UI components while the client manages all query binding, manages consistency, caching, and much more.  Apollo Client includes integrations with the most popular View lawyers such as React, React Native or Vue.

[Apollo iOS](https://github.com/apollographql/apollo-ios) is a strongly-typed GraphQL caching client for iOS written in Swift. It allows the execution of queries and mutations on a GraphQL server and returns the results as query-specific Swift types. This means that you do not have to deal with parsing JSON or making the client to cast values to the right type manually. Model types are generated from the GraphQL definitions your application's UI.

[Apollo Android](https://github.com/apollographql/apollo-kotlin) is a GraphQL client for generating Java models from GraphQL queries, giving you a typesafe API to work with your GraphQL servers. Although it’s designed mainly for Android, you can use it in any Java/Kotlin app.

[Apollo CLI](https://github.com/apollographql/apollo-tooling) is a simple command line client that merges your GraphQL clients and servers with features such as validation of your GraphQL schema, securing compatibility of your server operations, or generating static types for client-side type security.

## A solution for development teams

GraphQL is all about collaboration. Development teams that work collaboratively on their GraphQL API achieve the best results. To facilitate this collaboration Apollo team created some useful solutions such as:

* Schema Registry - a registry for GraphQL schemas that functions as a central source of truth for a schema, enriched with additional metadata such as field-level usage statistics.
* Client registry — a registry to track each known schema user, both pre-registered and ad-hoc consumers.
* Operation registry — a registry of all the known operations against the schema
* Trace warehouse — a data pipeline that stores a detailed log of every operation performed against your schema. All these registries work collectively to give your development team a good understanding of the API.
* Safelisting - locking your API down to trusted, pre-registered operations. Apollo CLI extracts all the queries from a client codebase and stores it in the operation registry. Separately, an Apollo Server plugin synchronizes the list of pre-registered operations to the server, which then rejects queries that aren’t present in its local copy.
* Schema validation - which tests a proposed schema against the known set of operations observed in production, returning a list of affected clients for each breaking change.
* GraphQL Gateway - a configuration of Apollo Server, along with some add-ons that functions as a GraphQL Gateway. The gateway composes separately deployed “micro-schemas” that reference each other into a single master schema, which looks to a client just like any regular GraphQL schema. To answer queries, the gateway builds a query plan, fetches data from each upstream GraphQL service, and assembles it all back together into a single result.

![graphql.webp](https://graphqleditorcms.fra1.cdn.digitaloceanspaces.com/graphqleditorcms/blogpost/graphql.webp)

Blog