GraphQL
Call the API, then learn how schemas and controllers expose platform services.
Call the GraphQL API
The local Compose endpoint is http://bosca.localhost:3000/graphql. Authenticate using the login mutation, then send the access token as a bearer token. For example, after setting BOSCA_TOKEN to the returned token:
This category query requires editor authority. GraphQL responses can contain an errors array even when HTTP succeeds; check both data and errors. The following sections cover extending the Kotlin backend.
Schema Files
GraphQL schemas are .graphqls files under src/main/resources/graphql/:
Schema Registration
Each module declares which schema files to load with a @Schemas interface:
KSP generates schema registrars for the declared resources. The application loads its selected registrars to build the schema. A schema file must be listed and its registrar loaded to become available.
TypeController & Fields
@TypeController marks a class as the field resolver for a GraphQL type. The type is inferred from GraphQLController<T>. Each method is annotated with @Field:
A parameter matching the controller's model type receives the parent object. Other parameters supply arguments or request context.
Automatic Parameter Injection
| Parameter Type | What It Provides |
|---|---|
AuthenticationContext | Request authentication context; its principal can be null |
AuthenticationContext? | Nullable form of the request authentication context |
Batch<K, V> | DataLoader batch context |
ResolverContext | Bosca GraphQL resolver environment |
ServerCall | Underlying HTTP request |
All other parameters map to GraphQL field arguments by name.
The Namespace Pattern
Top-level fields return singleton objects, which are resolved by their own @TypeController:
This creates the query path: query { content { categories { all { ... } } } }
Complete every wiring layer when adding a domain: schema registrar, root namespace field, nested namespace fields, and controller dispatcher registrar. Keep GraphQL argument nullability and defaults in the SDL; a Kotlin default argument does not make an SDL argument optional.
Mutation Controllers
Mutations follow the same namespace pattern with separate mutation objects:
AuthenticationContext parameter alone does not require a logged-in principal. Subscriptions
Subscription fields return Flow<T>, often backed by PubSubService. The server's collection subscription authenticates the caller and checks collections:view for scoped tokens before subscribing. This is an excerpt using the existing readSubscription helper:
Batching (DataLoader)
Use Batch<K, V> in field resolvers to avoid N+1 queries:
The ServiceCache batch resolver handles loading all keys in a single query. See Caching for how batch resolvers are declared.