A GraphQL schema defines the data an API exposes to clients and the operations clients may perform. In a board-game API, it provides a way to make existing data and CRUD functionality available through GraphQL. section 10.2.3
The schema is organized around root operation types:
- Query exposes ways to retrieve data. It is required. section 10.2.3
- Mutation exposes insert, update, and delete operations. It is optional. section 10.2.3
- Subscription lets clients receive notifications about events. It is optional and, unlike Query and Mutation, must retain state for each active subscription. section 10.2.3
For a straightforward CRUD API, start with Query and Mutation; a Subscription is not needed. A Query class can provide methods that return board games, domains, and mechanics from ApplicationDbContext. The example query methods also carry paging, projection, filtering, and sorting attributes. section 10.2.3
Listing 10.2 /GraphQL/Query.cs file
using MyBGList.Models;
namespace MyBGList.GraphQL
{
public class Query
{
[Serial]
[UsePaging]
[UseProjection]
[UseFiltering]
[UseSorting]
public IQueryable<BoardGame> GetBoardGames( #1
[Service] ApplicationDbContext context)
=> context.BoardGames;
[Serial]
[UsePaging]
[UseProjection]
[UseFiltering]
[UseSorting]
public IQueryable<Domain> GetDomains( #2
[Service] ApplicationDbContext context)
=> context.Domains;
[Serial]
[UsePaging]
[UseProjection]
[UseFiltering]
[UseSorting]
public IQueryable<Mechanic> GetMechanics( #3
[Service] ApplicationDbContext context)
=> context.Mechanics;
}
}
The Query class shows how retrieval methods and their attributes form the read side of the schema. section 10.2.3
Mutation methods handle writes; the board-game, domain, and mechanic examples include authorization attributes on update and delete methods. Register the Query and Mutation types with HotChocolate’s GraphQL server, add the supporting authorization and data features, then map the GraphQL endpoint. section 10.2.3
Listing 10.6 Program.cs file: GraphQL services
using MyBGList.GraphQL; #1
// [...]
builder.Services.AddGraphQLServer() #2
.AddAuthorization() #3
.AddQueryType<Query>() #4
.AddMutationType<Mutation>() #5
.AddProjections() #6
.AddFiltering() #7
.AddSorting(); #8
The service registration shows where the two root types and their supporting features are added. section 10.2.3
Do not confuse this API schema with a database schema. The database schema describes stored structures such as tables, fields, relationships, and constraints; EF Core migrations can generate and update it from a C# data model. The GraphQL schema instead describes what clients can access and do through the API. section 4.0 section 10.2.3
