Root Types: Query, Mutation, and Subscription
You'll learn how GraphQL organizes all API operations into three special entry-point types that define what clients can do.
The Three Entry Points
In GraphQL, every schema must define at least one root type that serves as the starting point for client requests. Think of these like the front doors to your API—each door leads to a different kind of interaction.
Query: Reading Data
The Query type is the main entry point for fetching data. It's like asking questions: "What users exist?" or "Show me this product's details." Every GraphQL schema must have a Query type—it's the only required root type.
type Query {
user(id: ID!): User
products: [Product!]!
searchPosts(keyword: String!): [Post!]!
}
Mutation: Writing Data
The Mutation type handles operations that change data—creating, updating, or deleting. It's like giving commands: "Create this user" or "Delete that post." While optional, nearly all real-world APIs include this type.
type Mutation {
createUser(name: String!, email: String!): User!
updateProduct(id: ID!, price: Float!): Product!
deletePost(id: ID!): Boolean!
}
Subscription: Real-Time Updates
The Subscription type enables real-time, event-driven updates. Clients "subscribe" to specific events and receive pushed updates when they occur—like receiving notifications when new messages arrive.
type Subscription {
messageAdded(channelId: ID!): Message!
userStatusChanged(userId: ID!): UserStatus!
}
Why Three Separate Types?
This separation makes your API's capabilities explicit and self-documenting. Clients know exactly where to look for read operations, write operations, or real-time features.
Key Takeaway: GraphQL organizes all API operations into three root types—Query for reads, Mutation for writes, and Subscription for real-time updates—with Query being the only required type.