graphql-api

GraphQL API Patterns

Schema Design (SDL)

# schema.graphql
type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: Pagination): UserConnection!
  posts(authorId: ID, published: Boolean): [Post!]!
}

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

type Subscription {
  messageAdded(chatId: ID!): Message!
}

type User {
  id: ID!
  email: String!
  name: String!
  posts: [Post!]!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
  author: User!
  tags: [String!]!
}

# Pagination (Relay-style)
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}
type UserEdge { node: User!; cursor: String! }
type PageInfo { hasNextPage: Boolean!; endCursor: String }

# Input types
input CreateUserInput {
  email: String!
  name: String!
  password: String!
}

input UserFilter {
  role: Role
  search: String
}

input Pagination {
  first: Int
  after: String
}

# Error handling — union pattern
union UserPayload = User | UserError
type UserError { message: String!; code: String! }

enum Role { USER ADMIN }
scalar DateTime

Server Setup (Strawberry / Python)

# graphql_app.py
import strawberry
from strawberry.fastapi import GraphQLRouter
from strawberry.types import Info

@strawberry.type
class User:
    id: strawberry.ID
    email: str
    name: str

    @strawberry.field
    async def posts(self, info: Info) -> list["Post"]:
        return await info.context["loaders"].posts_by_user.load(self.id)

@strawberry.type
class Query:
    @strawberry.field
    async def user(self, id: strawberry.ID, info: Info) -> User | None:
        return await info.context["db"].get_user(id)

    @strawberry.field
    async def users(self) -> list[User]:
        return await info.context["db"].list_users()

@strawberry.type
class Mutation:
    @strawberry.mutation
    async def create_user(self, email: str, name: str, info: Info) -> User:
        return await info.context["db"].create_user(email=email, name=name)

schema = strawberry.Schema(query=Query, mutation=Mutation)

# FastAPI integration
graphql_app = GraphQLRouter(schema, context_getter=get_context)
app.include_router(graphql_app, prefix="/graphql")