# GraphQL 101 A practical, experience-driven series on building GraphQL APIs — from schema design fundamentals through federated microservices using TypeScript and Python in production. ## Why This Series? I came to GraphQL after spending years building REST APIs. REST worked well for standard CRUD but became painful when a frontend team wanted different field subsets, or when a mobile app needed to reduce the number of round-trips on a slow network. The classic REST problem: either overfetch (the endpoint returns more than needed) or underfetch (you need five endpoints to build one screen). GraphQL solves this by letting clients request exactly the fields they need. Once I understood the type system, resolvers, and the DataLoader pattern, I stopped writing endpoint after endpoint and started thinking in graphs. This series documents what I learned building a real project: a TypeScript-based GraphQL gateway that federates data from multiple microservices — one in TypeScript (the primary service) and one in Python using Strawberry (a catalogue service). Federation is where GraphQL goes from useful to genuinely powerful in a microservices architecture. ## What You'll Learn * Understand GraphQL's type system: types, interfaces, unions, enums, scalars, and directives * Design schemas that are easy to evolve without versioning * Build a production-grade GraphQL server with TypeScript and Apollo Server 4 * Build a Python GraphQL subgraph with Strawberry * Write queries, mutations, and real-time subscriptions * Authenticate and authorise requests at the field and type level * Federate multiple GraphQL services into a single API graph * Solve the N+1 problem with DataLoader * Test resolvers and federated schemas with Jest and pytest * Deploy and monitor GraphQL services in production ## Technology Stack ### TypeScript Services * **Runtime**: Node.js 20+ * **Language**: TypeScript 5.x * **GraphQL Server**: Apollo Server 4 * **Schema**: Schema-first SDL + `graphql-tag` * **Federation**: Apollo Federation v2 (`@apollo/subgraph`, Apollo Router) * **ORM**: Prisma 5 (PostgreSQL) * **Data loading**: DataLoader * **Auth**: JWT (`jsonwebtoken`), bcrypt * **Validation**: Zod * **Testing**: Jest, `@apollo/server/testing` * **Subscriptions**: `graphql-ws` over WebSocket ### Python Service * **Language**: Python 3.11+ * **GraphQL Server**: Strawberry (code-first, fully typed) * **Federation**: Strawberry Apollo Federation extension * **Web framework**: FastAPI * **ORM**: SQLAlchemy 2.x (async) * **Testing**: pytest, `strawberry.testing` ## Prerequisites * TypeScript and Node.js fundamentals * Python fundamentals (classes, async/await, type annotations) * PostgreSQL basics * Basic Docker knowledge ## Series Structure ### Part 1: [Introduction to GraphQL and the Schema Definition Language](https://blog.htunnthuthu.com/getting-started/programming/graphql-101/part-1-introduction-graphql-sdl) Understand what GraphQL is, how it fundamentally differs from REST, and how the SDL describes an API. Set up TypeScript and Python environments. **Key Topics**: * GraphQL query language and runtime * SDL: types, fields, scalars, non-null * Queries, mutations, and subscriptions explained * REST vs GraphQL tradeoffs — when to use which * Setting up Apollo Server 4 with TypeScript *** ### Part 2: [Schema Design and the GraphQL Type System](https://blog.htunnthuthu.com/getting-started/programming/graphql-101/part-2-schema-design-type-system) Master the full GraphQL type system. Design schemas that model real domains correctly and evolve gracefully. **Key Topics**: * Object types, interfaces, unions, and enums * Custom scalars (Date, JSON, UUID) * Input types vs output types * Schema-first vs code-first approaches * Naming conventions and schema evolution without versioning * Directives: `@deprecated`, `@skip`, `@include`, custom directives *** ### Part 3: [Building a GraphQL API with TypeScript and Apollo Server](https://blog.htunnthuthu.com/getting-started/programming/graphql-101/part-3-building-graphql-api-typescript) Build a complete GraphQL API from scratch with TypeScript, Apollo Server 4, and Prisma. Implement resolvers, context, data sources, and subscriptions. **Key Topics**: * Apollo Server 4 project structure * Resolver chain execution * Context: database client, auth user, data loaders * Solving the N+1 problem with DataLoader * Mutations with input validation (Zod) * Real-time subscriptions with `graphql-ws` *** ### Part 4: [GraphQL Client Development — TypeScript and Python](https://blog.htunnthuthu.com/getting-started/programming/graphql-101/part-4-graphql-client-typescript-python) Consume GraphQL APIs from both TypeScript frontends and Python backend services. Cover code generation, type-safe queries, and inter-service communication. **Key Topics**: * Apollo Client in TypeScript: queries, mutations, cache * GraphQL Code Generator for type-safe TypeScript operations * Python `gql` client: consuming a GraphQL API from a Python service * Persisted queries and query batching * Error handling on the client side *** ### Part 5: [Authentication and Authorization in GraphQL](https://blog.htunnthuthu.com/getting-started/programming/graphql-101/part-5-authentication-authorization) Secure GraphQL APIs at the operation, type, and field level. Implement JWT authentication and role-based access control without middleware spaghetti. **Key Topics**: * JWT authentication with Apollo Server context * Field-level and type-level authorization with custom resolvers * Schema directives for declarative auth (`@auth`, `@hasRole`) * Protecting subscriptions * Auth in the Python Strawberry subgraph *** ### Part 6: [GraphQL Federation — TypeScript Gateway and Python Subgraph](https://blog.htunnthuthu.com/getting-started/programming/graphql-101/part-6-graphql-federation-typescript-python) Compose TypeScript and Python GraphQL services into a single unified API graph using Apollo Federation v2. **Key Topics**: * Federation concepts: subgraphs, supergraph, entities, `@key` * TypeScript subgraph with Apollo Server and `@apollo/subgraph` * Python subgraph with Strawberry and FastAPI * Apollo Router as the composition gateway * Cross-service entity references: `@extends`, `@external` * Incremental migration strategy from monolith to federated graph *** ### Part 7: [Testing, Performance, and Production Deployment](https://blog.htunnthuthu.com/getting-started/programming/graphql-101/part-7-testing-performance-deployment) Test GraphQL resolvers thoroughly, optimise for production load, and deploy with observability. **Key Topics**: * Unit testing resolvers with Jest and Apollo's `executeOperation` * Integration testing with real database (Testcontainers) * Python subgraph testing with `strawberry.testing` * Persisted queries for production performance * Query complexity analysis and depth limiting (security) * Deployment: Docker, environment variables, Apollo Studio * Distributed tracing with OpenTelemetry *** ## Getting Started ### TypeScript Setup ```bash mkdir graphql-api && cd graphql-api npm init -y npm install apollo-server-core graphql @apollo/server @apollo/subgraph \ graphql-tag graphql-ws dataloader jsonwebtoken zod winston \ prisma @prisma/client npm install -D typescript tsx @types/node @types/jsonwebtoken \ @graphql-codegen/cli @graphql-codegen/typescript jest @types/jest ts-jest npx tsc --init ``` ### Python Setup ```bash python -m venv .venv && source .venv/bin/activate pip install strawberry-graphql[fastapi] "strawberry-graphql[federation]" \ fastapi uvicorn sqlalchemy asyncpg gql pytest pytest-asyncio ``` Jump to [Part 1](https://blog.htunnthuthu.com/getting-started/programming/graphql-101/part-1-introduction-graphql-sdl) to begin.