About GraphQL Java Servlet

Implementation of GraphQL Java Servlet including support for Relay.js, Apollo and OSGi out of the box. This project wraps the Java implementation of GraphQL provided by GraphQL Java. The documentation on this site focuses around the usage of the servlet. Although some parts may dive deeper into the aspects of GraphQL Java as well, make sure to look at the GraphQL Java documentation for more in depth details regarding GraphQL Java itself.

We try to stay up to date with GraphQL Java as much as possible. The current version supports GraphQL Java 19.3.

This project requires at least Java 17.

Quick start

See Getting started for more detailed instructions.

To add graphql-java-servlet to your project and get started quickly, do the following.

Build with Gradle

Make sure mavenCentral is amongst your repositories:

repositories {
    mavenCentral()
}

Add the graphql-java-servlet dependency:

dependencies {
    compile 'com.graphql-java-kickstart:graphql-java-servlet:15.0.0'
}

Build with Maven

Add the graphql-java-servlet dependency:

<dependency>
  <groupId>com.graphql-java-kickstart</groupId>
  <artifactId>graphql-java-servlet</artifactId>
  <version>15.0.0</version>
</dependency>

Create a Servlet class

Creating the Servlet class requires various parameters to be provided at the moment. We’re working on simplifying this, to make it easier to get started. For now, take a look at Create a Servlet class to see what’s needed to create a Servlet with a schema.

Using the latest development build

Snapshot versions of the current master branch are availble on JFrog. Check the next snapshot version on Github

Build with Gradle

Add the Snapshot repository:

repositories {
    mavenCentral()
    maven { url "https://oss.jfrog.org/artifactory/oss-snapshot-local" }
}

Build with Maven

Add the Snapshot repository:

<repositories>
  <repository>
    <id>oss-snapshot-local</id>
    <name>jfrog</name>
    <url>https://oss.jfrog.org/artifactory/oss-snapshot-local</url>
    <snapshots>
      <enabled>true</enabled>
      <updatePolicy>always</updatePolicy>
    </snapshots>
  </repository>
</repositories>

Usage

The servlet supports the following request formats:

• GET request to ../schema.json: Get the result of an introspection query.
• GET request with query parameters (query only, no mutation):
  • query
  • operationName (optional)
  • variables (optional)
• POST body JSON object with fields:
  • query
  • operationName (optional)
  • variables (optional)
• POST multipart part named “graphql” containing JSON object with fields:
  • query
  • operationName (optional)
  • variables (optional)
• POST multipart parts named “query”, “operationName” (optional), and “variables” (optional)
• POST with Content Type “application/graphql” will treat the HTTP POST body contents as the GraphQL query string

Spring Framework support

To use the servlet with Spring Framework, either use the Spring Boot starter or simply define a ServletRegistrationBean in a web app:

@Bean
ServletRegistrationBean graphQLServletRegistrationBean(GraphQLSchema schema, ExecutionStrategy executionStrategy, List<GraphQLOperationListener> operationListeners) {
    return new ServletRegistrationBean(new SimpleGraphQLServlet(schema, executionStrategy, operationListeners), "/graphql");
}

GraphQL Subscription support

Subscriptions over WebSocket are fully supported within Spring Boot, but may require some work if you’re using another framework. There is an example here. Internally, JSR 356 is used for WebSocket support. The endpoint is GraphQLWebSocketServlet.