User Getting Started

Getting Started with Graphite

This guide will help you get started with Graphite, a type-safe GraphQL client for Spring Boot.

Prerequisites

• Java 21 or higher
• Gradle 8.5+ or Maven 3.8+
• A GraphQL server with an introspection schema

Step 1: Add Dependencies

Gradle (Kotlin DSL)

plugins {
    id("io.github.graphite") version "0.1.0"
}

dependencies {
    implementation("io.github.graphite:graphite-spring-boot-starter:0.1.0")
    testImplementation("io.github.graphite:graphite-test-utils:0.1.0")
}

graphite {
    schemaFile = file("src/main/resources/graphql/schema.json")
    packageName = "com.example.graphql"
}

Gradle (Groovy DSL)

plugins {
    id 'io.github.graphite' version '0.1.0'
}

dependencies {
    implementation 'io.github.graphite:graphite-spring-boot-starter:0.1.0'
    testImplementation 'io.github.graphite:graphite-test-utils:0.1.0'
}

graphite {
    schemaFile = file('src/main/resources/graphql/schema.json')
    packageName = 'com.example.graphql'
}

Maven

<plugin>
    <groupId>io.github.graphite</groupId>
    <artifactId>graphite-maven-plugin</artifactId>
    <version>0.1.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <schemaFile>${project.basedir}/src/main/resources/graphql/schema.json</schemaFile>
        <packageName>com.example.graphql</packageName>
    </configuration>
</plugin>

<dependencies>
    <dependency>
        <groupId>io.github.graphite</groupId>
        <artifactId>graphite-spring-boot-starter</artifactId>
        <version>0.1.0</version>
    </dependency>
    <dependency>
        <groupId>io.github.graphite</groupId>
        <artifactId>graphite-test-utils</artifactId>
        <version>0.1.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Step 2: Obtain Your GraphQL Schema

Graphite generates code from a GraphQL introspection schema in JSON format. You can obtain this from your GraphQL server.

Using graphql-cli

# Install graphql-cli (requires npm)
npm install -g graphql-cli

# Fetch the schema
graphql get-schema --endpoint https://api.example.com/graphql --json > src/main/resources/graphql/schema.json

Using curl with introspection query

curl -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { types { name } } }"}' \
  > src/main/resources/graphql/schema.json

Manual download

Many GraphQL tools (GraphQL Playground, Apollo Studio, etc.) allow you to download the introspection schema directly.

Step 3: Configure the Client

Add configuration to application.yml:

graphite:
  url: https://api.example.com/graphql
  headers:
    Authorization: Bearer ${GRAPHQL_TOKEN}
  timeout:
    connect: 10s
    read: 30s

See Configuration-Reference for all available options.

Step 4: Generate Code

Gradle

./gradlew graphiteGenerate

Generated code will be in build/generated/sources/graphite/.

Maven

mvn graphite:generate

Generated code will be in target/generated-sources/graphite/.

Step 5: Use the Generated Code

The generated code includes:

• Query classes - For each query operation in your schema
• Mutation classes - For each mutation operation
• Type classes - DTOs for all GraphQL types
• Input classes - For input types
• Enum classes - For all GraphQL enums

Example: Executing a Query

import org.springframework.stereotype.Service;
import io.github.graphite.GraphiteClient;
import com.example.graphql.query.GetUserQuery;
import com.example.graphql.type.UserDTO;

@Service
public class UserService {

    private final GraphiteClient client;

    public UserService(GraphiteClient client) {
        this.client = client;
    }

    public UserDTO getUser(String id) {
        // Build a type-safe query with field selection
        var query = GetUserQuery.builder()
            .id(id)
            .selecting(s -> s
                .id()
                .name()
                .email()
                .createdAt())
            .build();

        // Execute and get the result
        var response = client.execute(query);

        // Handle potential errors
        if (response.hasErrors()) {
            throw new RuntimeException("GraphQL errors: " + response.errors());
        }

        return response.data();
    }
}

Example: Executing a Mutation

import com.example.graphql.mutation.CreateUserMutation;
import com.example.graphql.input.CreateUserInput;

public UserDTO createUser(String name, String email) {
    var input = CreateUserInput.builder()
        .name(name)
        .email(email)
        .build();

    var mutation = CreateUserMutation.builder()
        .input(input)
        .selecting(s -> s.id().name().email())
        .build();

    return client.execute(mutation).getDataOrThrow();
}

Example: Async Execution

public CompletableFuture<UserDTO> getUserAsync(String id) {
    var query = GetUserQuery.builder()
        .id(id)
        .selecting(s -> s.id().name())
        .build();

    return client.executeAsync(query)
        .thenApply(response -> response.getDataOrThrow());
}

Step 6: Write Tests

Graphite provides testing utilities for mocking GraphQL responses:

import io.github.graphite.test.GraphiteMockServer;
import org.junit.jupiter.api.Test;
import java.util.Map;

class UserServiceTest {

    @Test
    void shouldFetchUser() {
        try (GraphiteMockServer server = GraphiteMockServer.create()) {
            // Stub the GraphQL response
            server.stubQuery("GetUser", Map.of(
                "id", "123",
                "name", "John Doe",
                "email", "john@example.com"
            ));

            // Create client pointing to mock server
            GraphiteClient client = GraphiteClient.builder()
                .endpoint(URI.create(server.getUrl()))
                .build();

            // Test your service
            UserService service = new UserService(client);
            UserDTO user = service.getUser("123");

            // Verify results
            assertThat(user.id()).isEqualTo("123");
            assertThat(user.name()).isEqualTo("John Doe");

            // Verify the query was made
            server.verify("GetUser", 1);
        }
    }
}

Next Steps

• Configuration-Reference - Learn about all configuration options
• Advanced-Usage - Custom scalars, interceptors, and more
• Troubleshooting - Common issues and solutions