BoscaDeveloper Documentation

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:

bash

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/:

graphql

Schema Registration

Each module declares which schema files to load with a @Schemas interface:

kotlin

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:

kotlin

A parameter matching the controller's model type receives the parent object. Other parameters supply arguments or request context.

Automatic Parameter Injection

Parameter TypeWhat It Provides
AuthenticationContextRequest authentication context; its principal can be null
AuthenticationContext?Nullable form of the request authentication context
Batch<K, V>DataLoader batch context
ResolverContextBosca GraphQL resolver environment
ServerCallUnderlying 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:

Query controller
Wiring into the tree

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:

kotlin
Protected mutations explicitly check authentication and authorization through an evaluator before calling a service. An 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:

kotlin

Batching (DataLoader)

Use Batch<K, V> in field resolvers to avoid N+1 queries:

kotlin

The ServiceCache batch resolver handles loading all keys in a single query. See Caching for how batch resolvers are declared.