GraphQL API Design and Implementation: Building Efficient and Scalable APIsh1

# Define types first
type User {
  id: ID!
  email: String!
  profile: UserProfile
  posts: [Post!]!
  followers: [User!]!
  following: [User!]!
  createdAt: DateTime!
}

type UserProfile {
  id: ID!
  displayName: String!
  bio: String
  avatar: String
  location: String
  website: String
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  tags: [Tag!]!
  comments: [Comment!]!
  likes: [User!]!
  publishedAt: DateTime!
  updatedAt: DateTime!
}

type Comment {
  id: ID!
  content: String!
  author: User!
  post: Post!
  createdAt: DateTime!
}

type Tag {
  id: ID!
  name: String!
  posts: [Post!]!
}

# Define operations
type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): [User!]!
  posts(limit: Int, offset: Int, authorId: ID): [Post!]!
  post(id: ID!): Post
  searchPosts(query: String!): [Post!]!
  trendingTags: [Tag!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!

  createPost(input: CreatePostInput!): Post!
  updatePost(id: ID!, input: UpdatePostInput!): Post!
  deletePost(id: ID!): Boolean!

  followUser(userId: ID!): Boolean!
  unfollowUser(userId: ID!): Boolean!

  likePost(postId: ID!): Boolean!
  unlikePost(postId: ID!): Boolean!
}

input CreateUserInput {
  email: String!
  password: String!
  displayName: String!
  bio: String
}

input UpdateUserInput {
  displayName: String
  bio: String
  location: String
  website: String
}

input CreatePostInput {
  title: String!
  content: String!
  tagIds: [ID!]!
}

input UpdatePostInput {
  title: String
  content: String
  tagIds: [ID!]
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

enum UserRole {
  USER
  MODERATOR
  ADMIN
}

input PostFilter {
  status: PostStatus
  authorId: ID
  tagIds: [ID!]
  dateFrom: DateTime
  dateTo: DateTime
}

input PaginationInput {
  limit: Int!
  offset: Int!
  sortBy: String
  sortOrder: SortOrder
}

enum SortOrder {
  ASC
  DESC
}

type Query {
  posts(filter: PostFilter, pagination: PaginationInput): PostConnection!
}

type PostConnection {
  posts: [Post!]!
  totalCount: Int!
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

import { ApolloServer } from '@apollo/server'
import { startStandaloneServer } from '@apollo/server/standalone'
import DataLoader from 'dataloader'

// DataLoader for N+1 problem prevention
const userLoader = new DataLoader(async (userIds: readonly string[]) => {
  const users = await db.user.findMany({
    where: { id: { in: Array.from(userIds) } },
  })
  return userIds.map((id) => users.find((user) => user.id === id) || null)
})

const postLoader = new DataLoader(async (postIds: readonly string[]) => {
  const posts = await db.post.findMany({
    where: { id: { in: Array.from(postIds) } },
    include: { author: true, tags: true },
  })
  return postIds.map((id) => posts.find((post) => post.id === id) || null)
})

// Resolvers
const resolvers = {
  Query: {
    user: async (_: any, { id }: { id: string }) => {
      return await userLoader.load(id)
    },

    users: async (_: any, { limit = 10, offset = 0 }: { limit?: number; offset?: number }) => {
      return await db.user.findMany({
        take: limit,
        skip: offset,
        orderBy: { createdAt: 'desc' },
      })
    },

    posts: async (_: any, { filter, pagination }: { filter?: any; pagination?: any }) => {
      const where: any = {}

      if (filter?.status) where.status = filter.status
      if (filter?.authorId) where.authorId = filter.authorId
      if (filter?.tagIds?.length) {
        where.tags = { some: { id: { in: filter.tagIds } } }
      }
      if (filter?.dateFrom || filter?.dateTo) {
        where.publishedAt = {}
        if (filter.dateFrom) where.publishedAt.gte = filter.dateFrom
        if (filter.dateTo) where.publishedAt.lte = filter.dateTo
      }

      const totalCount = await db.post.count({ where })

      const posts = await db.post.findMany({
        where,
        take: pagination?.limit || 10,
        skip: pagination?.offset || 0,
        orderBy: {
          [pagination?.sortBy || 'publishedAt']: pagination?.sortOrder === 'ASC' ? 'asc' : 'desc',
        },
        include: { author: true, tags: true },
      })

      return {
        posts,
        totalCount,
        hasNextPage: (pagination?.offset || 0) + posts.length < totalCount,
        hasPreviousPage: (pagination?.offset || 0) > 0,
      }
    },
  },

  Mutation: {
    createPost: async (_: any, { input }: { input: CreatePostInput }, context: Context) => {
      if (!context.user) {
        throw new GraphQLError('Not authenticated', {
          extensions: { code: 'UNAUTHENTICATED' },
        })
      }

      // Validate input
      if (input.title.length < 5) {
        throw new GraphQLError('Title must be at least 5 characters', {
          extensions: { code: 'BAD_USER_INPUT' },
        })
      }

      // Check if tags exist
      const existingTags = await db.tag.findMany({
        where: { id: { in: input.tagIds } },
      })

      if (existingTags.length !== input.tagIds.length) {
        throw new GraphQLError('One or more tags do not exist', {
          extensions: { code: 'BAD_USER_INPUT' },
        })
      }

      // Create post
      const post = await db.post.create({
        data: {
          title: input.title,
          content: input.content,
          authorId: context.user.id,
          tags: {
            connect: input.tagIds.map((id) => ({ id })),
          },
        },
        include: { author: true, tags: true },
      })

      return post
    },
  },

  User: {
    posts: async (user: User) => {
      return await db.post.findMany({
        where: { authorId: user.id },
        orderBy: { publishedAt: 'desc' },
      })
    },

    followers: async (user: User) => {
      const followers = await db.follow.findMany({
        where: { followingId: user.id },
        include: { follower: true },
      })
      return followers.map((f) => f.follower)
    },

    following: async (user: User) => {
      const following = await db.follow.findMany({
        where: { followerId: user.id },
        include: { following: true },
      })
      return following.map((f) => f.following)
    },
  },

  Post: {
    author: async (post: Post) => {
      return await userLoader.load(post.authorId)
    },

    tags: async (post: Post) => {
      return await db.tag.findMany({
        where: {
          posts: { some: { id: post.id } },
        },
      })
    },

    comments: async (post: Post) => {
      return await db.comment.findMany({
        where: { postId: post.id },
        include: { author: true },
        orderBy: { createdAt: 'asc' },
      })
    },

    likes: async (post: Post) => {
      const likes = await db.like.findMany({
        where: { postId: post.id },
        include: { user: true },
      })
      return likes.map((l) => l.user)
    },
  },

  Comment: {
    author: async (comment: Comment) => {
      return await userLoader.load(comment.authorId)
    },

    post: async (comment: Comment) => {
      return await postLoader.load(comment.postId)
    },
  },
}

import jwt from 'jsonwebtoken'
import { GraphQLError } from 'graphql'

interface Context {
  user: User | null
  dataSources: {
    userAPI: UserAPI
    postAPI: PostAPI
  }
}

// Create context for each request
const createContext = async ({ req }: { req: Request }): Promise<Context> => {
  const token = req.headers.authorization?.replace('Bearer ', '')

  let user = null
  if (token) {
    try {
      const decoded = jwt.verify(token, process.env.JWT_SECRET!) as any
      user = await db.user.findUnique({
        where: { id: decoded.userId }
      })
    } catch (error) {
      // Token invalid or expired
    }
  }

  return {
    user,
    dataSources: {
      userAPI: new UserAPI(),
      postAPI: new PostAPI()
    }
  }
}

// Authentication directive
const authDirectiveTransformer = (schema: GraphQLSchema, directiveName: string) => {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig, fieldName, typeName) => {
      const authDirective = getDirective(schema, fieldConfig, directiveName)?.[0]

      if (authDirective) {
        const { resolve = defaultFieldResolver } = fieldConfig

        fieldConfig.resolve = async (source, args, context, info) => {
          if (!context.user) {
            throw new GraphQLError('Not authenticated', {
              extensions: { code: 'UNAUTHENTICATED' }
            })
          }

          // Check roles if specified
          const requiredRoles = authDirective.roles
          if (requiredRoles && !requiredRoles.includes(context.user.role)) {
            throw new GraphQLError('Insufficient permissions', {
              extensions: { code: 'FORBIDDEN' }
            })
          }

          return resolve(source, args, context, info)
        }
      }

      return fieldConfig
    }
  })
}

// Usage in schema
type Mutation {
  createPost(input: CreatePostInput!): Post! @auth
  deletePost(id: ID!): Boolean! @auth(roles: ["ADMIN"])
  updateUser(id: ID!, input: UpdateUserInput!): User! @auth(roles: ["ADMIN"])
}

// Before DataLoader (N+1 problem)
const resolvers = {
  User: {
    posts: async (user) => {
      // This causes N+1 if N users are queried
      return await db.post.findMany({
        where: { authorId: user.id },
      })
    },
  },
}

// After DataLoader (batched queries)
const postLoader = new DataLoader(async (authorIds) => {
  const posts = await db.post.findMany({
    where: {
      authorId: { in: Array.from(authorIds) },
    },
  })

  // Group posts by authorId
  const postsByAuthor = posts.reduce(
    (acc, post) => {
      if (!acc[post.authorId]) {
        acc[post.authorId] = []
      }
      acc[post.authorId].push(post)
      return acc
    },
    {} as Record<string, typeof posts>
  )

  // Return in same order as requested
  return authorIds.map((id) => postsByAuthor[id] || [])
})

const resolvers = {
  User: {
    posts: async (user) => {
      return await postLoader.load(user.id)
    },
  },
}

import { createComplexityPlugin } from 'graphql-query-complexity'

// Complexity plugin
const complexityPlugin = createComplexityPlugin({
  schema,
  rules: [
    {
      operationName: 'Query.posts',
      complexity: 2,
      multipliers: ['pagination.limit'],
    },
    {
      operationName: 'User.posts',
      complexity: 1,
    },
  ],
  maximumComplexity: 100,
  onComplete: (complexity) => {
    console.log('Query Complexity:', complexity)
  },
})

// Usage in Apollo Server
const server = new ApolloServer({
  schema,
  plugins: [complexityPlugin],
  introspection: process.env.NODE_ENV !== 'production',
})

import { GraphQLError } from 'graphql'
import DOMPurify from 'isomorphic-dompurify'

// Input validation middleware
const validateInput = (input: any, rules: ValidationRule[]): void => {
  for (const rule of rules) {
    const value = input[rule.field]

    if (rule.required && (value === undefined || value === null || value === '')) {
      throw new GraphQLError(`${rule.field} is required`, {
        extensions: { code: 'BAD_USER_INPUT', field: rule.field },
      })
    }

    if (value && rule.minLength && value.length < rule.minLength) {
      throw new GraphQLError(`${rule.field} must be at least ${rule.minLength} characters`, {
        extensions: { code: 'BAD_USER_INPUT', field: rule.field },
      })
    }

    if (value && rule.maxLength && value.length > rule.maxLength) {
      throw new GraphQLError(`${rule.field} must be no more than ${rule.maxLength} characters`, {
        extensions: { code: 'BAD_USER_INPUT', field: rule.field },
      })
    }

    if (value && rule.pattern && !rule.pattern.test(value)) {
      throw new GraphQLError(`${rule.field} format is invalid`, {
        extensions: { code: 'BAD_USER_INPUT', field: rule.field },
      })
    }
  }
}

// Sanitization function
const sanitizeHTML = (html: string): string => {
  return DOMPurify.sanitize(html, {
    ALLOWED_TAGS: ['p', 'br', 'strong', 'em', 'u'],
    ALLOWED_ATTR: [],
  })
}

// Secure mutation
const resolvers = {
  Mutation: {
    createPost: async (_: any, { input }: { input: CreatePostInput }, context: Context) => {
      // Validate authentication
      if (!context.user) {
        throw new GraphQLError('Not authenticated', {
          extensions: { code: 'UNAUTHENTICATED' },
        })
      }

      // Validate input
      validateInput(input, [
        { field: 'title', required: true, minLength: 5, maxLength: 200 },
        { field: 'content', required: true, minLength: 10, maxLength: 10000 },
      ])

      // Sanitize content
      const sanitizedContent = sanitizeHTML(input.content)

      // Check for spam
      if (containsSpam(sanitizedContent)) {
        throw new GraphQLError('Content contains inappropriate material', {
          extensions: { code: 'BAD_USER_INPUT' },
        })
      }

      // Rate limiting check
      const recentPosts = await db.post.count({
        where: {
          authorId: context.user.id,
          createdAt: {
            gte: new Date(Date.now() - 60 * 1000), // Last minute
          },
        },
      })

      if (recentPosts >= 5) {
        throw new GraphQLError('Too many posts created recently', {
          extensions: { code: 'RATE_LIMITED' },
        })
      }

      // Create post
      return await db.post.create({
        data: {
          title: input.title,
          content: sanitizedContent,
          authorId: context.user.id,
        },
      })
    },
  },
}

// In-memory cache for frequently accessed data
class CacheManager {
  private cache = new Map<string, { data: any; expiry: number }>()

  set(key: string, data: any, ttlSeconds: number = 300): void {
    this.cache.set(key, {
      data,
      expiry: Date.now() + ttlSeconds * 1000,
    })
  }

  get(key: string): any | null {
    const item = this.cache.get(key)

    if (!item) return null
    if (Date.now() > item.expiry) {
      this.cache.delete(key)
      return null
    }

    return item.data
  }

  invalidate(pattern: string): void {
    for (const [key] of this.cache) {
      if (key.includes(pattern)) {
        this.cache.delete(key)
      }
    }
  }
}

// Redis cache for distributed caching
class RedisCache {
  constructor(private redis: RedisClient) {}

  async get(key: string): Promise<any> {
    const data = await this.redis.get(key)
    return data ? JSON.parse(data) : null
  }

  async set(key: string, data: any, ttlSeconds: number = 300): Promise<void> {
    await this.redis.setex(key, ttlSeconds, JSON.stringify(data))
  }

  async invalidate(pattern: string): Promise<void> {
    const keys = await this.redis.keys(pattern)
    if (keys.length > 0) {
      await this.redis.del(keys)
    }
  }
}

// GraphQL response caching
const responseCachePlugin = {
  async requestDidStart({ request, contextValue }: any) {
    // Check cache before execution
    const cacheKey = `graphql:${hash(request.query)}:${JSON.stringify(request.variables)}`

    const cached = await contextValue.redisCache.get(cacheKey)
    if (cached) {
      return { response: cached }
    }

    return {
      async willSendResponse({ response }: any) {
        // Cache successful responses
        if (response.errors?.length === 0) {
          await contextValue.redisCache.set(cacheKey, response, 300)
        }
      },
    }
  },
}

import { PubSub } from 'graphql-subscriptions'
import { withFilter } from 'graphql-subscriptions'

const pubsub = new PubSub()

// Subscription resolvers
const resolvers = {
  Subscription: {
    postCreated: {
      subscribe: withFilter(
        () => pubsub.asyncIterator('POST_CREATED'),
        (payload, variables) => {
          // Filter by author if specified
          if (variables.authorId) {
            return payload.postCreated.authorId === variables.authorId
          }
          return true
        }
      ),
    },

    commentAdded: {
      subscribe: withFilter(
        () => pubsub.asyncIterator('COMMENT_ADDED'),
        (payload, variables) => {
          // Only send comments for posts the user follows
          return payload.commentAdded.postId === variables.postId
        }
      ),
    },
  },
}

// Publish events in mutations
const resolvers = {
  Mutation: {
    createPost: async (_: any, { input }: { input: CreatePostInput }, context: Context) => {
      const post = await db.post.create({
        data: {
          title: input.title,
          content: input.content,
          authorId: context.user.id,
        },
      })

      // Publish event
      await pubsub.publish('POST_CREATED', {
        postCreated: post,
      })

      return post
    },

    addComment: async (_: any, { input }: { input: AddCommentInput }, context: Context) => {
      const comment = await db.comment.create({
        data: {
          content: input.content,
          authorId: context.user.id,
          postId: input.postId,
        },
        include: { author: true, post: true },
      })

      // Publish event
      await pubsub.publish('COMMENT_ADDED', {
        commentAdded: comment,
      })

      return comment
    },
  },
}

import { ApolloServer } from '@apollo/server'
import { createTestClient } from 'apollo-server-testing'
import gql from 'graphql-tag'

// Test utilities
const createTestServer = (contextValue?: any) => {
  const server = new ApolloServer({
    schema,
    context: () => ({ ...contextValue }),
  })

  return createTestClient(server)
}

// Unit tests for resolvers
describe('User Resolver', () => {
  it('should return user by id', async () => {
    const mockUser = { id: '1', email: 'test@example.com' }
    const mockDb = { user: { findUnique: jest.fn().mockResolvedValue(mockUser) } }

    const server = createTestServer({ db: mockDb })

    const query = gql`
      query GetUser($id: ID!) {
        user(id: $id) {
          id
          email
        }
      }
    `

    const { data } = await server.query({ query, variables: { id: '1' } })

    expect(data?.user).toEqual(mockUser)
    expect(mockDb.user.findUnique).toHaveBeenCalledWith({
      where: { id: '1' },
    })
  })
})

// Integration tests
describe('Posts API Integration', () => {
  let testDb: any

  beforeAll(async () => {
    testDb = await setupTestDatabase()
  })

  afterAll(async () => {
    await teardownTestDatabase(testDb)
  })

  it('should create post and return it', async () => {
    const server = createTestServer({
      db: testDb,
      user: { id: '1', email: 'test@example.com' },
    })

    const mutation = gql`
      mutation CreatePost($input: CreatePostInput!) {
        createPost(input: $input) {
          id
          title
          content
          author {
            id
            email
          }
        }
      }
    `

    const { data, errors } = await server.mutate({
      mutation,
      variables: {
        input: {
          title: 'Test Post',
          content: 'Test content',
        },
      },
    })

    expect(errors).toBeUndefined()
    expect(data?.createPost.title).toBe('Test Post')
    expect(data?.createPost.author.email).toBe('test@example.com')
  })
})

// Performance tests
describe('GraphQL Performance', () => {
  it('should handle complex queries efficiently', async () => {
    const server = createTestServer()

    const complexQuery = gql`
      query ComplexQuery {
        posts(limit: 100) {
          id
          title
          content
          author {
            id
            email
            profile {
              displayName
              bio
            }
          }
          tags {
            id
            name
          }
          comments {
            id
            content
            author {
              id
              email
            }
          }
          likes {
            id
            email
          }
        }
      }
    `

    const startTime = Date.now()
    const { data } = await server.query({ query: complexQuery })
    const endTime = Date.now()

    expect(endTime - startTime).toBeLessThan(1000) // Should complete in < 1s
    expect(data?.posts).toHaveLength(100)
  })
})