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