GraphQLRequest

A typed GraphQL request payload.

Legacy: this serializer-coupled request type lives in :compat for backward compatibility with the deprecated co.anitrend.retrofit.graphql.converter.GraphConverter flow. New code should use the backend-neutral co.anitrend.retrofit.graphql.model.request.GraphQLOperationRequest with co.anitrend.retrofit.graphql.converter.GraphQLConverterFactory.

It is annotated with kotlinx.serialization.Serializable to enable serialization by KotlinxGraphQLJson when Retrofit passes a parameterized type like GraphQLRequest<GetMarketPlaceAppsVariables>.

When using the codegen Gradle plugin, generated operation objects provide .request(...) factory methods that construct co.anitrend.retrofit.graphql.model.request.GraphQLOperationRequest instances with type-safe variable classes. For asset-based workflows, construct GraphQLRequest manually or use QueryContainerBuilder.

Serialization Behavior

kotlinx.serialization

• query, operationName, and variables are serialized normally

• extensions remains @Transient on the data class because Map<String, Any?> cannot be statically resolved by the compiler plugin

• KotlinxGraphQLJson.encode merges supported extension payloads into the encoded JSON at runtime so common request extensions, including APQ, continue to work on the typed request flow

Gson (via GsonGraphQLJson)

• All fields are serialized normally, including extensions

Accessing extensions with kotlinx

withPersistedQuery() already works through KotlinxGraphQLJson.encode without a custom serializer. For other extension values (e.g. custom protocol extensions, vendor-specific metadata), define your own @Serializable request wrapper with concrete JSON element types. No custom serializer is required unless the actual wire structure needs transformation:

@Serializable
data class JsonGraphQLRequest<TVariables : GraphQLVariables>(
    val query: String,
    val operationName: String,
    val variables: TVariables? = null,
    val extensions: JsonObject? = null,
)

Use this wrapper only as the request body type for endpoints whose extension payloads are already represented as JSON. Keep using GraphQLRequest when KotlinxGraphQLJson.encode can encode the extension values directly. withPersistedQuery() handles APQ without any custom serializer. This example covers arbitrary extension payloads beyond APQ.

APQ behavior

withPersistedQuery() still works with KotlinxGraphQLJson for the typed GraphQLRequest flow. The runtime encoder merges extensions.persistedQuery into the outgoing JSON even though extensions stays @Transient on the data class. The legacy QueryContainerBuilder flow remains Gson-backed.

Usage

Manual (asset-based):

val request = GraphQLRequest<EmptyGraphQLVariables>(
    query = "query GetCurrentUser { viewer { login } }",
    operationName = "GetCurrentUser",
)

Type Parameters

See also