GraphQL Fundamentals Skill Skill

GraphQL Fundamentals Skill

Master the building blocks of GraphQL APIs

Overview

This skill covers the essential GraphQL concepts every developer needs. From type definitions to query operations, you'll learn the foundation for building GraphQL APIs.

Quick Reference

| Concept | Syntax | Example | |---------|--------|---------| | Scalar | String, Int, Float, Boolean, ID | name: String! | | Object | type Name { fields } | type User { id: ID! } | | Input | input Name { fields } | input CreateUserInput { name: String! } | | Enum | enum Name { VALUES } | enum Status { ACTIVE INACTIVE } | | List | [Type] or [Type!]! | tags: [String!]! | | Non-null | Type! | id: ID! |

Core Concepts

1. Type System

# Scalar types (built-in)
type Example {
  id: ID!           # Unique identifier
  name: String!     # Text
  age: Int          # Integer (nullable)
  score: Float!     # Decimal
  active: Boolean!  # True/false
}

# Custom scalars
scalar DateTime
scalar JSON
scalar Upload

# Object types
type User {
  id: ID!
  email: String!
  profile: Profile    # Nested object
  posts: [Post!]!     # List of objects
}

type Profile {
  bio: String
  avatar: String
}

# Enums
enum UserRole {
  ADMIN
  EDITOR
  VIEWER
}

# Input types (for mutations)
input CreateUserInput {
  email: String!
  name: String!
  role: UserRole = VIEWER  # Default value
}

# Interfaces
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
}

# Unions
union SearchResult = User | Post | Comment

2. Queries

# Schema definition
type Query {
  # Single item
  user(id: ID!): User

  # List with optional filter
  users(filter: UserFilter, limit: Int = 10): [User!]!

  # Search
  search(query: String!): [SearchResult!]!
}

# Client query examples
query GetUser {
  user(id: "123") {
    id
    name
    email
  }
}

query GetUsersWithFilter {
  users(filter: { role: ADMIN }, limit: 5) {
    id
    name
  }
}

# With variables
query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
  }
}
# Variables: { "userId": "123" }

# With aliases
query GetTwoUsers {
  admin: user(id: "1") { name }
  editor: user(id: "2") { name }
}

# With fragments
fragment UserFields on User {
  id
  name
  email
}

query GetUsers {
  users {
    ...UserFields
  }
}

3. Mutations

# Schema definition
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): DeletePayload!
}

type CreateUserPayload {
  user: User
  errors: [Error!]!
}

# Client mutation
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      id
      name
    }
    errors {
      field
      message
    }
  }
}
# Variables: { "input": { "email": "test@example.com", "name": "Test" } }

4. Subscriptions

# Schema definition
type Subscription {
  userCreated: User!
  messageReceived(channelId: ID!): Message!
}

# Client subscription
subscription OnUserCreated {
  userCreated {
    id
    name
    createdAt
  }
}

subscription OnMessage($channelId: ID!) {
  messageReceived(channelId: $channelId) {
    id
    content
    sender { name }
  }
}

Common Patterns

Nullability Cheat Sheet

type Example {
  # Required field - never null
  id: ID!

  # Optional field - can be null
  nickname: String

  # Required list, optional items
  tags: [String]!        # [], ["a", null, "b"]

  # Required list, required items (most common)
  categories: [Category!]!  # [], [cat1, cat2]

  # Optional list (avoid - ambiguous)
  # items: [Item]  # null vs [] unclear
}

Input Validation Pattern

input CreateUserInput {
  email: String!      # Required
  name: String!       # Required
  age: Int            # Optional
  role: UserRole = VIEWER  # Optional with default
}

Troubleshooting

| Error | Cause | Solution | |-------|-------|----------| | Cannot query field "x" | Field not in schema | Check spelling, verify schema | | Variable "$x" not defined | Missing variable declaration | Add to query signature | | Expected non-null, got null | Resolver returned null for ! field | Fix resolver or make nullable | | Unknown type "X" | Type not defined | Add type definition |

Debug Commands

# Validate schema
npx graphql-inspector validate schema.graphql

# Introspect remote schema
npx graphql-inspector introspect http://localhost:4000/graphql

# Check for breaking changes
npx graphql-inspector diff old.graphql new.graphql

Usage

Skill("graphql-fundamentals")

Related Skills

graphql-schema-design - Advanced schema patterns
graphql-resolvers - Implementing resolvers
graphql-codegen - TypeScript type generation

Related Agent

01-graphql-fundamentals - For detailed guidance

Agent Skills: GraphQL Fundamentals Skill

Skill Files