Transports & Interception

**What Spring for GraphQL is.** Spring for GraphQL is the Spring integration on top of the graphql-java engine. Adding `spring-boot-starter-graphql` (usually alongside `spring-boot-starter-web` or `-webflux`) auto-configures a runnable GraphQL server. **The HTTP transport.** Unlike REST, GraphQL exposes a *single* endpoint. By default it is **`POST /graphql`** (change with the property `spring.graphql.path`). The HTTP method and URL never vary per operation — *what* you want is expressed entirely in the request body: ```json { "query": "query($id: ID!){ book(id:$id){ title } }", "operationName": null, "variables": { "id": "42" } } ``` The server always responds `200 OK` (even for GraphQL-level errors) with a JSON envelope: ```json { "data": { "book": { "title": "..." } }, "errors": [ ] } ``` `errors` is populated for validation or data-fetching failures; `data` and `errors` can coexist (partial results). Spring also supports **GET /graphql** for queries when explicitly used, and negotiates content type `application/graphql-response+json`. **Where the schema comes from.** By default Spring loads schema definition files matching `classpath:graphql/**/*.graphqls`. `@Controller` beans with `@QueryMapping`, `@MutationMapping`, `@SchemaMapping`, and `@SubscriptionMapping` methods supply the data fetchers. **GraphiQL.** GraphiQL (note the *i* — it is a specific open-source project, not just "graphical") is an in-browser IDE: schema documentation explorer, field autocomplete, and a console to run queries against your endpoint. The starter bundles a copy but it is **disabled by default**. Enable it: ```properties spring.graphql.graphiql.enabled=true # optional, defaults to /graphiql spring.graphql.graphiql.path=/graphiql ``` Then open `http://localhost:8080/graphiql`. **Gotchas / when-to-use.** - GraphiQL exposes your **entire schema** and lets any visitor run operations, so gate it: enable only in dev/staging, or put it behind auth. Do not ship it wide-open in production. - Introspection (the query GraphiQL uses to learn the schema) is on by default; you can disable it with `spring.graphql.schema.introspection.enabled=false` to harden production. - Because everything is one POST, standard REST tooling (per-path caching, HTTP verbs mapping to CRUD) does not apply — caching/observability are done differently. - 200-with-errors surprises people used to REST status codes; check the `errors` array, not the HTTP status, for GraphQL failures.