1. Home

GraphQL SPQR

This wiki is a work in progress, and does not provide full coverage of all GraphQL SPQR's capabilities. For more information on how GraphQL SPQR works you can check the example projects and the tests included within the project.

Welcome to the graphql-spqr wiki!

GraphQL SPQR (GraphQL Schema Publisher & Query Resolver, pronounced like speaker) is a simple-to-use library for rapid development of GraphQL APIs in Java.

Intro

GraphQL SPQR aims to make it dead simple to add a GraphQL API to any Java project. It works by dynamically generating a GraphQL schema from Java code.

• Requires minimal setup (~3 lines of code)
• Deeply configurable and extensible (not opinionated)
• Allows rapid prototyping and iteration (no boilerplate)
• Easily used in legacy projects with no changes to the existing code base
• Has very few dependencies

Code-first approach

When developing GraphQL-enabled applications it is common to define the schema first and hook up the business logic later. This is known as the schema-first style. While it has its advantages, in strongly and statically typed languages, like Java, it leads to a lot of duplication.

For example, a schema definition of a simple GraphQL type could like this:

type Link {
    id: ID!
    url: String!
    description: String
}

and, commonly, a corresponding Java type would exist in the system, similar to the following:

public class Link {
    
    private final String id;
    private final String url;
    private final String description;
    
    //constructors, getters and setters
    //...
}

Both of these blocks contain the exact same information. Worse yet, changing one requires an immediate change to the other. This makes refactoring risky and cumbersome, and the compiler can not help. On the other hand, if you’re trying to introduce a GraphQL API into an existing project, writing the schema practically means re-describing the entire existing model. This is both expensive and error-prone, and still suffers from duplication and lack of tooling.

Instead, GraphQL SPQR takes the code-first approach, by generating the schema from the existing model. This keeps the schema and the model in sync, easing refactoring. It also works well in projects where GraphQL is introduced on top of an existing codebase.

Still schema-first

Note that developing in the code-first style is still effectively schema-first, the difference is that you develop your schema not in yet another language, but in Java, with your IDE, the compiler and all your tools helping you. Breaking changes to the schema mean the compilation will fail. No need for linters or other fragile hacks.