GraphQL file types in Apollo Kotlin
Apollo Kotlin supports the following file types for GraphQL definitions:
.json
forintrospection schemas.graphqls
forSDL schemas.graphql
foroperations(queries, mutations, and subscriptions)
To learn more about SDL schemas, see the
Schemas
A GraphQL schema describes a graph's data types and the relationships between those types. Apollo Kotlin supports JSON schemas obtained via
Introspection schemas (.json
)
.json
)You can obtain a GraphQL server's schema via a special
{"data": {"__schema": {"queryType": {"name": "Query"},"mutationType": {"name": "Mutation"},"types": [...]}}}
Some JSON schemas omit the top-level data
field. Apollo Kotlin supports this omission.
Tools like downloadApolloSchema
Gradle task:
./gradlew :app:downloadApolloSchema \--endpoint "https://example.com/graphql" \--schema schema.json
JSON introspection schemas are verbose and difficult to read or modify. For simplicity, you should consider JSON schemas read-only and convert them to
SDL schemas (.graphqls
)
.graphqls
)SDL (Schema Definition Language) is the canonical language for defining GraphQL schemas as defined in the
type schema {query: Querymutation: Mutation}type Query {field: String @deprecated...}
You can't use introspection to download an SDL schema directly from a GraphQL endpoint. However, Apollo Kotlin can convert an introspection schema to SDL automatically if you specify the .graphqls
extension in the --schema
option:
./gradlew :app:downloadApolloSchema \--endpoint "https://example.com/graphql" \--schema schema.graphqls
Apollo Kotlin also supports the .sdl
file extension for SDL schemas, but very few other tools use .sdl
. You should use .graphqls
moving forward.
Operations (.graphql
)
.graphql
)GraphQL operations are executed against a graph to fetch or modify data.
In Apollo Kotlin, operation files use the .graphql
(without 's'
) extension. These files only contain
query MyQuery {field1field2...}
Apollo Kotlin compiles these operations into type-safe models that you can use at runtime.