Schema Design

Workshop

Eve Porcello

@eveporcello

Agenda

  • Intro to the Schema Definition Language
  • Creating Schema Types
  • Nullable vs. Non-nullable Fields
  • Design Considerations

Tahoe City, CA

 

GraphQL is a spec that describes:

A Query Language

A Schema Definition Language

GraphQL Scalar Types

Int

Float

String

Boolean

ID

id: ID!

name: String!

GraphQL Scalar Types

type Photo {

      id: ID!

      name: String!

      url: String!

      description: String

      rating: Float

      private: Boolean!

}

GraphQL Object Types

name: String!

Nullable vs. Non-nullable

description: String

  type Query {

      totalUsers: Int!

  }

 

Root Queries

  type Query {

      totalUsers(role: ROLE!): Int!

  }

 

Arguments

type User {

   postedPhotos: [Photo!]!

}

 

Lists

photos: [Photo]

Nullable vs. Non-nullable Lists

photos: [Photo]!

photos: [Photo!]!

Nullable list of nullable values

Non-nullable list of nullable values

Non-nullable list of non-nullable values

Enums

 enum PhotoCategory {

      PORTRAIT

      ACTION

      LANDSCAPE

  }


Root Mutation

type Mutation {

    postPhoto: Boolean!

}

 

Arguments

type Mutation {

      postPhoto (name: String!): Photo!

 }

 

Input Types

input PostPhotoInput {

    name: String!

    category: PhotoCategory=PORTRAIT

    description: String

}

Input Types

 mutation addPhoto ($input: PostPhotoInput!) {

      postPhoto(input: $input) {

         id

         name

         url

  }  

}

{

   "input":  {

     "name": "Desert Sunset",

     "description": "Sunset over Sedona",

     "category": "LANDSCAPE"

   }

}

Query Variables

Root Subscription

type Subscription {

  newPhoto: Photo!

}

 

Custom Scalars

scalar DateTime

 

type Photo {

     created: DateTime!

     updated: DateTime!

}

One-to-One Connection

  type Photo {

      postedBy: User!

  }

 

One-to-Many Connection

type User {

   postedPhotos: [Photo!]!

}

 

Many-to-Many Connection

type Student {

      schedule: [Course!]!

}

type Course {

      students: [Student!]!

}

City to City

type City {

     name: String!

     connections: [City!]!

}

 

BOISE

SUN VALLEY

BEND

155 MILES

318 MILES

Through Types

type City {

     name: String!

     connections: [Connection!]!

}

 

type Connection {

     distance: Int!

     to: City!

}

BOISE

SUN VALLEY

155 MILES

BEND

318 MILES

Through Types w/ Pagination

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: ID!
  endCursor: ID!
}
type CityEdge {
  node: City!
  cursor: ID!
}
type City {
  name: String!
  connections(
     first: Int!, 
     after: ID!
  ): [CityConnection!]!
}
type CityConnection {
  edges: [CityEdge]
  pageInfo: PageInfo!
}

Building the

Pet Library Schema

Agenda

  • Interfaces & Union Types
  • Filtering & Pagination
  • Scaling a Schema

Keep In Mind:

  • What Clients Need

  • Specific, Consistent Naming

  • Custom Objects Over Scalar Values

Union Types

type Schedule {

    agenda: [AgendaItem!]!

}

union AgendaItem = StudyGroup | Workout

query {

    agenda {

        ...on Workout {

           name

           reps

       }

        ...on StudyGroup {

           name

           subject

           students

       }

  }

}

Query

Interfaces

interface ScheduleItem {

    name: String!

    start: Int

    end: Int

}

type StudyGroup implements ScheduleItem {

      name: String!

      start: Int

      end: Int

      students: Int!

}

type Workout implements ScheduleItem {

      name: Location!

      start: Int

      end: Int

      reps: Int!

}

type Query {

      agenda: [ScheduleItem!]!

}

enum PetCategory

DOG

CAT

STINGRAY

RABBIT

type Pet

id: ID!

name: String!

category: PetCategory!

        ...

HORSE

sleepAmount: Int

curious: Boolean

favoriteFood: String

floppy: Int

good: Boolean

chill: Boolean

fast: Boolean

streetsmart: Boolean

majestic: Boolean

interface Pet

type Cat implements Pet

id: ID!

name: String

...

sleepAmount: Int

curious: Boolean

id: ID!

name: String!

weight: Float

status: PetStatus

photo: Photo

dueDate: Date

inCareOf: Customer

type Dog implements Pet

id: ID!

name: String

...

good: Boolean

type Rabbit implements Pet

id: ID!

name: String

...

favoriteFood: String

floppy: Int

type Stingray 

implements Pet

id: ID!

name: String

...

chill: Boolean

fast: Boolean

type Horse 

implements Pet

id: ID!

name: String

...

streetsmart: Boolean

majestic: Boolean

type *TBDFuturePet 

implements Pet

id: ID!

name: String

...

newField: _____

newField: _____

Union Types

type Query {

    familyPets: [FamilyPets!]!

}

union FamilyPet = Cat | Dog

Query

query {
  familyPets {
    __typename
    ...on Cat {
      name
      weight
    }
    ...on Dog {
      name
      status
    }
  }
}

Apollo - Schema Design

By Moon Highway

Apollo - Schema Design

Schema Design Workshop

  • 829