GraphQL file types in Apollo Kotlin
Apollo Kotlin supports the following file types for GraphQL definitions:
.json
for introspection schemas.graphqls
for SDL schemas.graphql
for operations (queries, mutations, and subscriptions)
To learn more about SDL schemas, see the blog post about SDL support in Apollo Kotlin.
Schemas
A GraphQL schema describes a graph's data types and the relationships between those types. Apollo Kotlin supports JSON schemas obtained via introspection, along with conventional SDL schemas.
Introspection schemas (.json
)
You can obtain a GraphQL server's schema via a special introspection query (assuming the server enables introspection). Like any other GraphQL server response, the returned schema is provided as JSON similar to the following:
{"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 Apollo Sandbox introspect a GraphQL server automatically and enable you to download its schema in JSON (or SDL) format. Apollo Kotlin can also download an introspected schema with the 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 if you need to make changes.
SDL schemas (.graphqls
)
SDL (Schema Definition Language) is the canonical language for defining GraphQL schemas as defined in the GraphQL spec. It's much cleaner and more expressive than JSON for understanding a schema's structure. It also supports directives, unlike the JSON representation (see this issue):
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 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 executable definitions (queries, mutations, subscriptions, and/or fragments):
query MyQuery {field1field2...}
Apollo Kotlin compiles these operations into type-safe models that you can use at runtime.