M05 — GraphQL & API Contracts

# ── Scalars ────────────────────────────────────────────────────── scalar DateTime # ISO-8601 string; validated by custom scalar coercion scalar UUID # ── Enums ──────────────────────────────────────────────────────── enum PostStatus { DRAFT PUBLISHED ARCHIVED } enum SortDirection { ASC DESC } # ── Interfaces ─────────────────────────────────────────────────── interface Node { id: ID! } # ── Object types ───────────────────────────────────────────────── type User implements Node { id: ID! username: String! email: String! createdAt: DateTime! posts(first: Int, after: String): PostConnection! } type Post implements Node { id: ID! title: String! body: String! status: PostStatus! author: User! tags: [String!]! createdAt: DateTime! } # ── Connection / Edge (Relay cursor pagination) ─────────────────── type PostConnection { edges: [PostEdge!]! pageInfo: PageInfo! totalCount: Int! } type PostEdge { node: Post! cursor: String! } type PageInfo { hasNextPage: Boolean! hasPreviousPage: Boolean! startCursor: String endCursor: String } # ── Input types (arguments for mutations) ──────────────────────── input CreatePostInput { title: String! body: String! tags: [String!] } # ── Union ───────────────────────────────────────────────────────── union SearchResult = User | Post # ── Root types ──────────────────────────────────────────────────── type Query { user(id: ID!): User posts(first: Int, after: String, status: PostStatus): PostConnection! search(query: String!): [SearchResult!]! } type Mutation { createPost(input: CreatePostInput!): Post! publishPost(id: ID!): Post! deletePost(id: ID!): Boolean! } type Subscription { postPublished: Post! commentAdded(postId: ID!): Comment! }

# Named query with variables and fragments query GetUserWithPosts($userId: ID!, $first: Int = 10) { user(id: $userId) { ...UserCore # fragment spread posts(first: $first) { edges { node { id title status author { ...UserCore } # reuse same fragment } cursor } pageInfo { hasNextPage endCursor } } } } fragment UserCore on User { id username email }

// Variables sent as a separate JSON object (NOT interpolated into the query string) { "userId": "abc-123", "first": 5 }

query Search($q: String!) { search(query: $q) { __typename # always include to discriminate union members ... on User { id username } ... on Post { id title status } } }

mutation CreateAndPublish($input: CreatePostInput!) { createPost(input: $input) { id title status author { id username } } } /* Response shape mirrors the selection set exactly */ { "data": { "createPost": { "id": "post-789", "title": "Hello World", "status": "DRAFT", "author": { "id": "abc-123", "username": "ajay" } } } }

query ConditionalQuery($withEmail: Boolean!, $skipTags: Boolean!) { user(id: "123") { id username email @include(if: $withEmail) # field included only if true posts(first: 5) { edges { node { title tags @skip(if: $skipTags) # field omitted if true } } } } }

# Client sends this once over WebSocket subscription WatchPost($postId: ID!) { commentAdded(postId: $postId) { id body author { id username } createdAt } } /* Server pushes one event per new comment: */ { "data": { "commentAdded": { "id": "c-42", "body": "Great post!", ... } } }

// Node.js / graphql-js pattern (pseudocode) const resolvers = { Subscription: { commentAdded: { // subscribe returns an AsyncIterator subscribe: (_, { postId }, { pubsub }) => pubsub.asyncIterableIterator(`COMMENT_ADDED_${postId}`), // resolve shapes each event payload resolve: (payload) => payload.commentAdded, }, }, Mutation: { addComment: async (_, { postId, body }, { db, pubsub, user }) => { const comment = await db.createComment({ postId, body, authorId: user.id }); await pubsub.publish(`COMMENT_ADDED_${postId}`, { commentAdded: comment }); return comment; }, }, };

/* HTTP response headers for SSE */ Content-Type: text/event-stream Cache-Control: no-cache Connection: keep-alive /* Each event is text/plain, double-newline terminated */ data: {"data":{"commentAdded":{"id":"c-42","body":"Hello!"}}} data: {"data":{"commentAdded":{"id":"c-43","body":"Nice!"}}}

/** * @param parent - resolved value of the parent object * @param args - field arguments from the query * @param context - shared request state: db, auth user, DataLoader instances * @param info - AST metadata: fieldName, returnType, path, schema */ async function userResolver(parent, { id }, { db, user }, info) { if (!user) throw new AuthenticationError('Must be logged in'); return db.users.findById(id); // returns Promise; runtime awaits it }

// DataLoader batches all loads queued in the same event-loop tick import DataLoader from 'dataloader'; // Batch function: receives array of keys, returns array of values (same order!) async function batchUsers(userIds) { const rows = await db.query('SELECT * FROM users WHERE id = ANY($1)', [userIds]); const map = Object.fromEntries(rows.map(r => [r.id, r])); return userIds.map(id => map[id] || new Error(`User ${id} not found`)); } // Create one DataLoader per REQUEST (not global — to avoid cross-request cache) function createContext({ req }) { return { db, user: authenticate(req), loaders: { user: new DataLoader(batchUsers), // one loader per entity type }, }; } // Resolver uses loader instead of direct DB call const resolvers = { Post: { author: (post, _, { loaders }) => loaders.user.load(post.authorId), }, };

query PaginatePosts($after: String, $first: Int = 10) { posts(first: $first, after: $after) { totalCount pageInfo { hasNextPage endCursor # pass this as $after in next request } edges { cursor # per-edge cursor (base64 opaque string) node { id title createdAt } } } }

// Cursor = base64( "PostCursor:" + sortKey ) // sortKey is typically the column used for ORDER BY function encodeCursor(sortValue) { return Buffer.from(`PostCursor:${sortValue}`).toString('base64'); } function decodeCursor(cursor) { const raw = Buffer.from(cursor, 'base64').toString('utf8'); // "PostCursor:2024-01-15T..." return raw.replace('PostCursor:', ''); } // Resolver builds SQL using decoded cursor async function postsResolver(_, { first = 10, after }, { db }) { const cursorValue = after ? decodeCursor(after) : null; const rows = await db.query( `SELECT * FROM posts WHERE ($1::timestamptz IS NULL OR created_at < $1) ORDER BY created_at DESC LIMIT $2`, [cursorValue, first + 1] // fetch +1 to detect hasNextPage ); const hasNextPage = rows.length > first; if (hasNextPage) rows.pop(); return { edges: rows.map(r => ({ node: r, cursor: encodeCursor(r.created_at) })), pageInfo: { hasNextPage, endCursor: rows.length ? encodeCursor(rows.at(-1).created_at) : null, }, totalCount: await db.count('posts'), }; }

# SDL for flexible filtering input PostFilter { status: PostStatus authorId: ID tags: [String!] createdAfter: DateTime createdBefore: DateTime } input PostSort { field: PostSortField! direction: SortDirection! } enum PostSortField { CREATED_AT TITLE AUTHOR_NAME } type Query { posts( first: Int, after: String, filter: PostFilter, sort: PostSort ): PostConnection! }

# Post subgraph — references User from User subgraph extend type User @key(fields: "id") { id: ID! @external # owned by User subgraph } type Post @key(fields: "id") { id: ID! title: String! author: User! # gateway will resolve via User subgraph }

/* Automatic Persisted Query (APQ) protocol */ /* Step 1 — Send hash only */ POST /graphql { "extensions": { "persistedQuery": { "version": 1, "sha256Hash": "abc123..." } } } /* Server responds with 404 if not cached */ { "errors": [{ "message": "PersistedQueryNotFound" }] } /* Step 2 — Resend with full query to register */ POST /graphql { "query": "query GetUser($id:ID!){user(id:$id){id username}}", "extensions": { "persistedQuery": { "version": 1, "sha256Hash": "abc123..." } } } /* Server caches query; subsequent requests use hash only */

# Introspection query — clients use this for schema discovery { __schema { types { name kind fields { name type { name kind } } } } } # Disable in production to prevent schema enumeration by attackers # Apollo Server: introspection: process.env.NODE_ENV !== 'production'

// Prevent deeply-nested or expensive queries from DoS-ing your server import { createComplexityRule } from 'graphql-query-complexity'; const server = new ApolloServer({ validationRules: [ createComplexityRule({ maximumComplexity: 1000, variables: {}, onComplete: (complexity) => console.log(`Query complexity: ${complexity}`), createError: (max, actual) => new Error(`Query too complex: ${actual} > ${max}`), }), ], depthLimit: 7, // reject queries deeper than 7 levels });

/* gql_lexer.h — minimal GraphQL lexer in C */ #include <stdio.h> #include <string.h> #include <ctype.h> typedef enum { TOK_NAME, TOK_INT, TOK_FLOAT, TOK_STRING, TOK_LBRACE, TOK_RBRACE, TOK_LPAREN, TOK_RPAREN, TOK_COLON, TOK_BANG, TOK_DOLLAR, TOK_AT, TOK_SPREAD, /* ... */ TOK_EOF, TOK_ERR } GqlTokKind; typedef struct { GqlTokKind kind; const char *start; size_t len; } GqlToken; typedef struct { const char *src; size_t pos; size_t len; } GqlLexer; static void gql_skip_ignored(GqlLexer *l) { while (l->pos < l->len) { char c = l->src[l->pos]; if (c == '#') { /* comment: skip to end of line */ while (l->pos < l->len && l->src[l->pos] != '\n') l->pos++; } else if (isspace(c) || c == ',') { l->pos++; /* commas are whitespace in GraphQL */ } else break; } } GqlToken gql_next_token(GqlLexer *l) { gql_skip_ignored(l); if (l->pos >= l->len) return (GqlToken){ TOK_EOF, NULL, 0 }; char c = l->src[l->pos]; if (isalpha(c) || c == '_') { size_t start = l->pos++; while (l->pos < l->len && (isalnum(l->src[l->pos]) || l->src[l->pos] == '_')) l->pos++; return (GqlToken){ TOK_NAME, l->src + start, l->pos - start }; } switch (c) { case '{': l->pos++; return (GqlToken){ TOK_LBRACE, l->src+l->pos-1, 1 }; case '}': l->pos++; return (GqlToken){ TOK_RBRACE, l->src+l->pos-1, 1 }; case '(': l->pos++; return (GqlToken){ TOK_LPAREN, l->src+l->pos-1, 1 }; case ')': l->pos++; return (GqlToken){ TOK_RPAREN, l->src+l->pos-1, 1 }; case ':': l->pos++; return (GqlToken){ TOK_COLON, l->src+l->pos-1, 1 }; case '!': l->pos++; return (GqlToken){ TOK_BANG, l->src+l->pos-1, 1 }; case '$': l->pos++; return (GqlToken){ TOK_DOLLAR, l->src+l->pos-1, 1 }; case '@': l->pos++; return (GqlToken){ TOK_AT, l->src+l->pos-1, 1 }; default: l->pos++; return (GqlToken){ TOK_ERR, l->src+l->pos-1, 1 }; } } int main(void) { const char *src = "{ user(id: \"abc\") { id username } }"; GqlLexer lexer = { src, 0, strlen(src) }; GqlToken tok; while ((tok = gql_next_token(&lexer)).kind != TOK_EOF) { printf("kind=%d text=%.*s\n", tok.kind, (int)tok.len, tok.start); } return 0; }