graphql-api

GraphQL API Skill

Step 1: Choose Your Stack

Step 2: Schema Design Principles

# ✅ Good schema design
type User {
  id: ID!
  name: String!
  email: String!
  posts(first: Int = 10, after: String): PostConnection!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  publishedAt: DateTime
  status: PostStatus!
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

# Relay-style cursor pagination (preferred for large datasets)
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 for mutations (keep separate from output types)
input CreatePostInput {
  title: String!
  content: String!
}

input UpdatePostInput {
  id: ID!
  title: String
  content: String
}

# Mutation return types - always return the mutated object
type CreatePostPayload {
  post: Post
  errors: [UserError!]!
}

type UserError {
  field: String
  message: String!
}

type Query {
  me: User
  user(id: ID!): User
  post(id: ID!): Post
  posts(first: Int, after: String, status: PostStatus): PostConnection!
}

type Mutation {
  createPost(input: CreatePostInput!): CreatePostPayload!
  updatePost(input: UpdatePostInput!): CreatePostPayload!
  deletePost(id: ID!): Boolean!
}

type Subscription {
  postCreated: Post!
  postUpdated(id: ID!): Post!
}

Step 3: Server Setup (TypeScript + GraphQL Yoga)

npm install graphql graphql-yoga

// app/api/graphql/route.ts (Next.js App Router)
import { createYoga, createSchema } from 'graphql-yoga'
import { typeDefs } from './schema'
import { resolvers } from './resolvers'
import { createContext } from './context'

const yoga = createYoga({
  schema: createSchema({ typeDefs, resolvers }),
  context: createContext,
  graphqlEndpoint: '/api/graphql',
  fetchAPI: { Response, Request, ReadableStream },
})

export { yoga as GET, yoga as POST }

// context.ts
import { NextRequest } from 'next/server'

export async function createContext({ request }: { request: NextRequest }) {
  const token = request.headers.get('authorization')?.replace('Bearer ', '')
  const user = token ? await verifyToken(token) : null
  return { user, db }
}