Field declaration

By default, it's valid for any field in your schema to return null instead of its specified type.

You can require that a particular field doesn't return null with an exclamation mark !, like so:

type Author {
  name: String! # Can't return null
  books: [Book!] # This list can be null but its list items can't be null
  articles: [Article!]! This list can't be null AND its list items can't be null
}

These fields are non-nullable. If your server attempts to return null for a non-nullable field, an error is thrown.

This is a cheatsheet:

Supported types

Scalar (Data types)
Object
This includes the three special root operation types: Query, Mutation, and Subscription.
Input
Enum
Union

Scalar types

Scalar types are similar to primitive types in your favorite programming language. They always resolve to concrete data.

GraphQL's default scalar types are:

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 (serialized as a String): A unique identifier that's often used to refetch an object or as the key for a cache. Although it's serialized as a String, an ID is not intended to be human‐readable.

Custom Scalar type

To define a custom scalar, add it to your schema like so:

scalar YesNo

You can now use this scalar as a type for your fields.

type Student {
  active: YesNo
}

However, it's only declared in GraphQL. To fully declare a custom scalar, you need to define ho Server interacts with it.

For instance, if you're using 99designs/gqlgen, you must follow this docs. In summary, you will need to define a Go type, implement the grqphql.Marshaler and graphql.UnMarshaler interfaces, and declare this type in gqlgen.yml.

(If you're using Apollo Graphql, you can follow this docs)

Object type

An object type contains a collection of fields, each of which has its own type.

For instnace, in the following declaration, Author is an Object type.

type Book {
  title: String
  author: Author
}

Every object type in your schema automatically has a field named __typename (you don't need to define it).
The __typename field returns the object type's name as a String (e.g., Book or Author). Clients can access this field the same way as they access other fields.

query Book {
 title
 author {
  __typename
  name
 }
}

Query type

The Query type is a special object type that defines all of the top-level entry points for queries that clients can request. It corresponds to API endpoints in RESTFul API.

type Query {
  books: [Book]
  book(id: ID): Book
}

This Query corresponds to the following APIs in RESTFul API:

/books
/books/:id

Read more about how client call queries here.

Mutation type

Mutation type defines entry points for write operations.

type Mutation {
  addBook(name: String, author_id: String): Book
}

Input type

If a query/mutation requires multiple arguments, you should create an Input type.

For example:

input EditBookRequest {
    book_id: ID!
    new_name: String!
}

type Mutation {
    renameBook(input: EditBookRequest): Book
}

Request:

mutation updateSomething($editBookRequest: EditBookRequest) {
    renameBook($editBookRequest) {
        name
    }   
}

Values:

{
  "editBookRequest": {
    "book_id": 1,
    "new_name": "2"
  }
}

Input types can’t have fields that are other objects, only basic scalar types, list types, and other input types.
Start with input keyword instead of type keyword.

Enum

Enum type define the allowed values for a type

enum AllowedColor {
  RED
  GREEN
  BLUE
}

type Query {
 changeColor(color: AllowedColor): Boolean
}

It restricts the input color to be within AllowedColor values.

Union type

Union types help us define a new type from a set of Types. An instance of this type may be one of the union's types.