graphql-api.md

Queries

Fields

An object property

{
  hero {
    name
    # subselection of fields for objects
    # ie returns only selected field for object
    friends {
      name
    }
  }
}

Arguments

Fields accept arguments

{
  human(id: "1000") {
    name
    height(unit: FOOT)
  }
}

Aliases

{
  empireHero: hero(episode: EMPIRE) {
    name
  } 
}

Fragments

Reusable units - sets of fields

#define fragment
fragment comparisonFields on Character {
  name
  appearsIn
  friends {
    name
  }
}

{
  leftComparison: hero(episode: EMPIRE) {
     ...comparisonFields
  }
  rightComparison: hero(episode: JEDI) {
     ...comparisonFields
  }
}

Variables

Named queries can accept a variable parameter

query HeroNameAndFriends($episode: Episode) {
    hero(episode: $episode) {
       name
    }
}

{
  "episode": "JEDI"
}

Default variables can also be set

query HeroNameAndFriends($episode: Episode = "JEDI) {
}

Operation name

Queries should be named

query QueryName {}

Directives

Field conditionals

query Hero($episode: Episode, $withFriends: Boolean!) {
  hero(episode: $episode) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

{
   "episode": "JEDI",
   "withFriends": false
}

Mutations

Explicit server-side modifications

mutation CreateReviewForEpisode($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
  }
}

{
  "ep": "JEDI",
  "review": {
    "stars": 5,
    "commentary": "review" 
  }
}

Inline fragments

Define fragments inline

query HeroForEpisode($ep: Episode!) {
  hero(episode: $ep) {
    name
    ... on Droid {
       primaryFunction
    } 
  }
}

Metafields

The __typename metafield return the name of the object type

{
    search() {
       __typename
    }
}

Schemas and Types

Object types

type Character {
    name: String!
    appearsIn: [Episode]!
}

# !: non-nullable
# []: array

Arguments

type Starship {
  length(unit: LengthUnit = METER): Float
}

Scalar types

No subfields

Int
Float #floating point value
String
Boolean
ID

#custom scalar types
scalar Date

Enumeration Types

A special kind of scalar

enum Episode {
   NEWHOPE
   EMPIRE
   JEDI
}

Interfaces

interface Character {
  id: ID!
  name: String!
  friends: [Character]
  appearsIn: [Episode]!
}

type Human implements Character {
  ...
}

Union types

union SearchResult = Human | Droid | Starship

Input types

input ReviewInput {
    stars: Int!
    commentary: String
}