Skip to content

Home

Jump to bottom
Maxwell edited this page Aug 2, 2026 · 9 revisions

Overview

retrofit-graphql is a Retrofit converter that injects .graphql query or mutation file contents into a request body along with any GraphQL variables. It supports runtime asset-based discovery and optional build-time code generation for type-safe request helpers.

Features

  • Automated persisted queries (APQ)
  • GraphQL fragment resolution (resolves fragment references)
  • Customizable logger (allows you to add a custom logger)
  • Customizable discovery plugin (allows you to define where and how to look for graphql files)
  • Backend-neutral request/response contracts (GraphQLOperationRequest, GraphQLResponse) with explicit transport codecs
  • Optional build-time code generation (operation constants, document registry, variable classes, response DTOs)

Two Workflows

Backend-Neutral (new)

  • GraphQLConverterFactory (:runtime) requires an explicit GraphQLTransportCodec (GsonGraphQLTransportCodec or KotlinxGraphQLTransportCodec) on every creation path.
  • Requests are GraphQLOperationRequest<TVariables>; responses are GraphQLResponse<T> with GraphQLData.Absent vs Present(null), typed error paths, and GraphQLValue extensions.
  • :api carries no serializer, Gson, or kotlinx dependency.

Deprecated Compatibility (:compat)

  • The legacy GraphConverter/GraphQLJson/GraphContainer/QueryContainerBuilder surface and the 37 io.github.wax911.library.* type aliases are deprecated but remain source- and binary-compatible, shipped exactly once from :compat (reachable through the deprecated :library aggregator).
  • Use it for existing asset-based @GraphQuery flows; new code should use the backend-neutral path.

Configuring the sample app

  • Register for an API key for the client, follow this guide
  • After acquiring an API key put it in the following directory ./app/.config/secrets.properties with the following format: token="YOUR_API_TOKEN_KEY_GOES_HERE"

See GraphQL File Uploads if you want to test that too.

Modular Architecture

The library is split into composable modules. The old :library aggregator is deprecated but still available for backward compatibility. See the Migration Guide for details on upgrading your project.

New capabilities:

  • Code Generation Plugin — Replace .graphql files in assets/ with build-time generated types. Apply id("co.anitrend.retrofit.graphql.codegen") to your project. See Code Generation for the full guide.
  • Type-Safe Request Helpers — Generated operation objects provide .request(...) factory methods returning the backend-neutral GraphQLOperationRequest<TVariables> with named, type-safe parameters.
  • Optional Response Models — Enable generateResponses to generate {OperationName}Data classes that match each operation's JSON shape, including aliases, conditionals, and abstract GraphQL types. Annotations are emitted per the strict serializationBackend setting (NONE/KOTLINX/GSON); NONE is never auto-selected or upgraded.
  • Enum Class Generation — GraphQL enum types generate as Kotlin enum classes.
  • Scalar Mappings — Map custom GraphQL scalars to Kotlin types via scalars { map("DateTime", "kotlin.String") } in the DSL.
  • Smaller Footprint — Depend only on the modules your project needs.
  • Registry-Based Resolution — Wire a GraphQLDocumentRegistry into the converter for faster query resolution without asset scanning.

Wiki Pages

Clone this wiki locally