How to write GraphQL schema
GraphQL (Graph Query Language) is an open-source data query and manipulation language for APIs and a runtime for fulfilling queries with existing data.
A GraphQL schema represents your application’s data graph and the operations on it. It also defines the queries and mutation functions to read and write data from the GraphQL server.
How do we design a GraphQL schema?
Think graph, not endpoints.
- Figure out client consumer use-cases. GraphQL lets API clients request and receive the exact data they ask for. With such a user-centered approach in mind, design your schema based on how data is used, not on how it’s stored.
For the purpose of this shot, we will write a simple bookshelf API. Our clients would like to know the list of books, books by a specific author, description of a book, etc.
- Identifying objects in your data that would form the nodes in your graph. You can do this by grouping together fields with their primary keys, making a single object. When you want to add a field to the graph to support a new feature, think about what object it belongs to, which can easily be done by thinking about the primary key for retrieving the value of the field.
Eg: Title, description of a book would be part of the Book object.
Think about naming the nodes and fields at this point, the node names need to be unique across the graph.
- Represent the relationship between different objects in your graph with edges between different nodes. The relationships will translate into our schema through different fields in the nodes. Try to have little dependency on other nodes when designing a graph so that it scales smoothly.
- Now that the data graph is formed, define operations on the graph with queries for READ and mutations for WRITE. Then, think about entry points in the graph and define queries based on the client’s needs and mutations based on what you need to add to the graph (and at which node).
Ex: GetBooks would get all books, their names, and author names.
How do we write the schema and operations?
A GraphQL schema is written in SDL ( schema definition language), which supports the following basic type categories:
- Scalar types: These are similar to primitive types of a programming language like
Int,Float,String,Boolean, andID. - Object types: An object type is a collection of fields that can be scalar or another object type. Relationships between two objects are defined by making one a field of another object.
type Book {id: ID!title: Stringauthor: Author}type Author {id: ID!name: Stringbooks: [Book]}
-
Arguments: Every field on a GraphQL object type can have zero or more named arguments.
-
The Query type: Query types define all of the top-level entry points for queries that the client executes against your data graph. Queries match the shape of the object types you define in your schema.
type Query {books: [Book]authors: [Author]}
query GetBooks {books {titleauthor {name}}}
- The Mutation type: Mutation types define entry points for write operations, matching the structure of schema type definitions. Mutations are executed against the schema with write data of the right type and structure.
type Mutation {addBook(title: String, author: String): Book}
More advanced type categories:
-
Input type: Input types are special object types that allow you to pass objects as arguments to queries and mutations.
-
The Enum type: An enum is similar to a scalar type, but its legal values are defined in the schema.
-
Interfaces: An Interface is an abstract type that includes a certain set of fields that a type must include to implement the interface.
-
Union type: Union types define the object types included in the union.
GraphQL schema defines the signature of your GraphQL API, but it’s not yet functional. Make it functional by building a server in the language of your choice, as mentioned in the official documentation.
