GraphQL Schema and API Design Guide
Design a well-structured, performant GraphQL schema with best practices for queries, mutations, subscriptions, and error handling.
Prompt Template
You are a senior API architect specializing in GraphQL. Help me design a production-ready GraphQL schema for the following application. **Application:** [e.g., multi-tenant project management SaaS] **Key entities:** [e.g., Users, Projects, Tasks, Comments, Teams] **Auth model:** [e.g., JWT with role-based access — admin, member, viewer] **Real-time needs:** [e.g., task status updates, new comments] **Existing data sources:** [e.g., PostgreSQL, Redis cache, external REST APIs] Deliver: 1. **Schema Design** — complete SDL with types, inputs, enums, interfaces, and unions where appropriate 2. **Query Design** — top-level queries with pagination (cursor-based), filtering, and sorting arguments 3. **Mutation Design** — mutations with proper input types, validation rules, and error union types 4. **Subscription Design** — real-time subscriptions for the specified use cases 5. **Relay Compliance** — Node interface, connection types, and global IDs if applicable 6. **N+1 Prevention** — DataLoader patterns and resolver optimization notes 7. **Auth Directives** — custom directives or middleware patterns for field-level authorization 8. **Error Handling** — structured error types vs GraphQL errors, when to use each 9. **Versioning Strategy** — how to evolve the schema without breaking clients 10. **Performance Considerations** — query complexity limits, depth limits, persisted queries Include inline comments explaining design decisions and trade-offs.
Example Output
GraphQL Schema: Project Management SaaS
Core Types
interface Node {
id: ID!
}
type User implements Node {
id: ID!
email: String!
displayName: String!
role: UserRole!
teams: [Team!]!
createdAt: DateTime!
}
enum UserRole {
ADMIN
MEMBER
VIEWER
}
type Project implements Node {
id: ID!
name: String!
description: String
team: Team!
tasks(first: Int, after: String, filter: TaskFilter): TaskConnection!
createdAt: DateTime!
updatedAt: DateTime!
}
# Cursor-based pagination
type TaskConnection {
edges: [TaskEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
Mutations with Error Unions
union CreateProjectResult = CreateProjectSuccess | ValidationError | AuthorizationError
type CreateProjectSuccess {
project: Project!
}
mutation {
createProject(input: CreateProjectInput!): CreateProjectResult!
}
N+1 Prevention
Use DataLoader for all `team`, `user`, and `tasks` resolvers. Batch by parent ID and cache per-request.
Auth Directive
directive @auth(requires: UserRole!) on FIELD_DEFINITION
Query Complexity
Set max depth: 7, max complexity: 1000. Use `graphql-query-complexity` for cost analysis.
Tips for Best Results
- 💡Start with your domain entities and relationships before writing resolvers
- 💡Use cursor-based pagination from day one — offset pagination breaks with real-time data
- 💡Return union types from mutations instead of throwing errors for expected failure cases
- 💡Add a query complexity analyzer to prevent abusive nested queries in production
Frequently Asked Questions
What is the GraphQL Schema and API Design Guide prompt?
Design a well-structured, performant GraphQL schema with best practices for queries, mutations, subscriptions, and error handling. It's a free ChatGPT prompt template from our Coding collection — copy it, fill in the bracketed variables, and paste it into your AI tool.
Which AI tools work with this prompt?
It's written and tested for ChatGPT, Claude and Gemini. Any AI assistant that accepts free-form text prompts will handle it well.
How do I customize this ChatGPT prompt?
Replace the bracketed variables — such as [e.g., task status updates, new comments] — with your own details before running it. Start with your domain entities and relationships before writing resolvers
Is this prompt free to use?
Yes. Every prompt on PromptAtlas is free to copy, customize, and use — no signup required.
Related Prompts
Python FileNotFoundError Debugging Prompt
Debug Python FileNotFoundError from the exact traceback, resolved path, working directory, filesystem context, deployment environment, and failing operation.
Python ZeroDivisionError Debugging Prompt
Debug Python ZeroDivisionError from the exact traceback, operand values and types, data path, numeric semantics, runtime context, and failing input.
Python IndentationError Debugging Prompt
Debug Python IndentationError from the exact parser message, whitespace, block structure, source bytes, formatter settings, and runtime version.
Python SyntaxError: Invalid Syntax Debugging Prompt
Debug Python SyntaxError invalid syntax from the exact parser location, surrounding tokens, Python version, generated code, execution context, and minimal reproduction.
Python AttributeError: Object Has No Attribute Debugging Prompt
Debug Python AttributeError from the exact traceback, runtime object type, attribute contract, construction path, version, imports, and minimal reproduction.
Python UnboundLocalError Debugging Prompt
Debug Python UnboundLocalError from the exact traceback, binding scope, assignments, branches, closures, imports, runtime path, and minimal reproduction.