/api-graphql-apollo-server

name: api-graphql-apollo-server
description: GraphQL API server with Apollo Server — schema, resolvers, context, error handling, data sources, plugins

GraphQL API with Apollo Server

> **Quick Guide:** Use `@apollo/server` (v5) for schema-first GraphQL APIs. Define schemas with SDL (`typeDefs`), implement field population with resolvers, share per-request state via the `context` function, and handle errors with `GraphQLError` + extension codes. Use `startStandaloneServer` for quick setups or integrate with your HTTP framework for production. DataLoader solves the N+1 problem. Plugins hook into the request lifecycle for logging, auth, and performance.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST import from `@apollo/server` -- NOT the deprecated `apollo-server` or `apollo-server-express` packages)**

**(You MUST create new data source and DataLoader instances per request in the context function -- sharing across requests causes data leaks)**

**(You MUST throw `GraphQLError` (from `graphql`) with extension codes for client-facing errors -- generic `Error` exposes stack traces)**

**(You MUST use `ApolloServerPluginDrainHttpServer` when integrating with an HTTP framework -- without it the server doesn't shut down gracefully)**

</critical_requirements>

---

**Auto-detection:** Apollo Server, @apollo/server, ApolloServer, startStandaloneServer, expressMiddleware, GraphQLError, typeDefs, resolvers, contextValue, DataLoader, RESTDataSource, @apollo/datasource-rest, ApolloServerPlugin, buildSubgraphSchema, @apollo/subgraph, graphql-ws, PubSub, formatError, gql tag

**When to use:**

• Building a GraphQL API with schema-first (SDL) design
• Defining typed resolvers with shared context (auth, data sources)
• Wrapping REST APIs or databases behind a unified GraphQL layer
• Implementing real-time features with subscriptions (via `graphql-ws`)
• Building federated subgraphs with `@apollo/subgraph`
• Adding lifecycle hooks with plugins (logging, auth, tracing)

**When NOT to use:**

• Simple REST APIs without nested data relationships (a REST framework is simpler)
• APIs consumed only by one client you control with no query flexibility needs
• Performance-critical APIs where schema overhead matters (consider a code-first approach)

**Key patterns covered:**

• Server setup with `startStandaloneServer` and framework middleware integration
• Resolver structure, arguments (`parent`, `args`, `contextValue`, `info`), and chains
• Context function for per-request state (auth tokens, data sources, DataLoaders)
• Error handling with `GraphQLError`, built-in codes, and `formatError`
• RESTDataSource for wrapping REST APIs with caching and deduplication
• DataLoader for batching and deduplication (N+1 problem)
• Custom plugins with server-level and request-level lifecycle hooks
• Subscriptions with `graphql-ws` and WebSocket server
• Federation subgraph setup with `@apollo/subgraph`

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Server setup, resolvers, context, error handling
• [examples/data-sources.md](examples/data-sources.md) - RESTDataSource, DataLoader, caching
• [examples/advanced.md](examples/advanced.md) - Subscriptions, federation, custom plugins
• [reference.md](reference.md) - Decision frameworks, anti-patterns, production checklist

---

<philosophy>

Philosophy

Apollo Server follows a **schema-first** approach: define your API contract in SDL, then implement resolvers to populate each field. The schema is the single source of truth for your API shape, documentation, and type system.

**Core principles:**

1. **Schema as contract** -- SDL defines what clients can query before implementation begins 2. **Thin resolvers** -- Resolvers orchestrate data fetching but delegate to data sources and services 3. **Per-request context** -- Each operation gets fresh data source instances and auth state via the context function 4. **Graceful error handling** -- `GraphQLError` with extension codes communicates errors without leaking internals

**Use Apollo Server when:**

• You need a unified API layer over multiple data sources (REST, DB, services)
• Clients benefit from querying exactly the data they need (mobile, varied frontends)
• Schema documentation and introspection matter for developer experience
• You want lifecycle plugins for observability, auth, and caching

**Use simpler approaches when:**

• A single REST endpoint suffices for your use case
• You have no nested data relationships worth expressing in a graph
• The overhead of schema definition and resolver wiring doesn't justify the flexibility

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Server Setup

Two approaches: `startStandaloneServer` for quick/simple setups, or framework middleware integration for production.

import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";

const server = new ApolloServer({ typeDefs, resolvers });

const DEFAULT_PORT = 4000;

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => ({
    token: req.headers.authorization,
  }),
  listen: { port: DEFAULT_PORT },
});

**Why good:** minimal boilerplate for development, context function provides per-request auth state

For production with an HTTP framework, use `expressMiddleware` (from `@as-integrations/express4` or `@as-integrations/express5`) with `ApolloServerPluginDrainHttpServer` for graceful shutdown.

See [examples/core.md](examples/core.md) for both setup patterns with full TypeScript types.

---

Pattern 2: Resolver Structure and Arguments

Resolvers receive four arguments: `parent` (return value from parent resolver), `args` (field arguments), `contextValue` (shared per-request state), and `info` (operation metadata).