typeDefs

typeDefs is a contract between the client and the server, stating that, eg. the server can return data about greeting that's of type String:

const { gql } = require("apollo-server");
const typeDefs = gql`
  type Query {
    greeting: String
    interestingUrls: [String]
  }
`;

This way the server guarantees the data shape.

type Query ​

In GraphQL it is ==mandatory== to create root type named Query. We can rename it, but then we'd need to redefine a schema as well:

const { gql } = require("apollo-server");

const typeDefs = gql`
  schema {
    query: RenamedQuery
  }

  type RenamedQuery {
    greeting: String
    interestingUrls: [String]
  }
`;

Supported types ​

Scalars ​

• String
• Int
• Float
  • GraphQL differentiates integers and floating points (as opposed to JS which treats both as Number)
• Boolean
• Id
  • basically a String, but has different purposes
• [String]

Enums ​

enum DayOfWeek {
  MON
  TUE
  WED
  THU
  FRI
  SAT
  SUN
}

type Query {
  today: DayOfWeek
}

In GraphQL enums are Strings (not Integers as in C++).

Object types ​

We cannot create nested types like in TypeScript - we need to define flat types and reuse them later:

type Quote {
  text: String!
  author: String!
}

type Query {
  randomQuote: Quote!
}

[!danger] Use of PascalCase is mandatory for every type in GraphQL.

non-nullable ​

If we won't provide value, GraphQL Server returns null. We can enforce returned value with ! (making type non-nullable):

type Query {
  today: DayOfWeek!
}

In arrays ​

type Query {
	workDays1: [DayOfWeek!] // GraphQL returns error if any of the array elements is `null`
	workDays2: [DayOfWeek]! // GraphQL returns error if the array is missing
	workDays3: [DayOfWeek!]! // both cases will cause an error
}

Empty array is a valid one.

[!tip] Always make values non-nullable

nullable types should be used only in specific cases.