GraphQL

Overview

Helidon MP implements the MicroProfile GraphQL specification. This specification describes how applications can be built to expose an endpoint for GraphQL. GraphQL is an open-source data query and manipulation language for APIs, and a runtime for fulfilling data queries. It provides an alternative to, though not necessarily a replacement for, REST.

Maven Coordinates

To enable MicroProfile GraphQL, add the following dependency to your project’s pom.xml (see Managing Dependencies).

<dependency>
  <groupId>io.helidon.microprofile.graphql</groupId>
  <artifactId>helidon-microprofile-graphql-server</artifactId>
</dependency>

API

The MicroProfile GraphQL specification defines a number of key annotations to be used when writing a GraphQL endpoint:

• @GraphQLApi - identifies a CDI Bean as a GraphQL endpoint
• @Query - identifies a method as returning one or more entities
• @Mutation - identifies a method which creates, deletes or updates entities

For example, the following defines a GraphQL endpoint with a number of queries and mutations that work against a fictional CustomerService service and Customer class.

Simple ContactGraphQLApi:

@ApplicationScoped
@GraphQLApi
public class ContactGraphQLApi {

    @Inject
    private CustomerService customerService;

    @Query
    public Collection<Customer> findAllCustomers() {1
        return customerService.getAllCustomers();
    }

    @Query
    public Customer findCustomer(@Name("customerId") int id) {2
        return customerService.getCustomer(id);
    }

    @Query
    public Collection<Customer> findCustomersByName(@Name("name") String name) {3
        return customerService.getAllCustomers(name);
    }

    @Mutation
    public Customer createCustomer(@Name("customerId") int id,4
                                  @Name("name") String name,
                                  @Name("balance") float balance) {
        return customerService.createCustomer(id, name, balance);
    }
}

public class customer {
    private int id;
    @NonNull
    private String name;
    private float balance;

    // getters and setters omitted for brevity
}

The example above would generate a GraphQL schema as shown below:

Sample GraphQL schema:

type Query {
   findAllCustomers: [Customer]
   findCustomer(customerId: Int!): Customer
   findCustomersByName(name: String): [Customers]
}

type Mutation {
   createCustomer(customerId: Int!, name: String!, balance: Float!): Customer
}

type Customer {
   id: Int!
   name: String!
   balance: Float
}

After application startup, a GraphQL schema will be generated from your annotated API classes and POJO’s and you will be able to access these via the URLs described below.

Building your application

As part of building your application, you must create a Jandex index using the jandex-maven-plugin for all API and POJO classes.

Generate Jandex index:

<plugin>
  <groupId>io.smallrye</groupId>
  <artifactId>jandex-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>make-index</id>
    </execution>
  </executions>
</plugin>

Accessing the GraphQL endpoints

After starting your application you should see a log message indicating that GraphQL is in the list of features. You can access the GraphQL endpoint at http://host:port/graphql, and the corresponding schema at http://host:port/graphql/schema.graphql. See Configuration for additional information on how to change the location of these resources. After starting your application you should see a log message indicating that GraphQL is in the list of features. You can access the GraphQL endpoint at http://host:port/graphql, and the corresponding schema at http://host:port/graphql/schema.graphql. See Configuration for additional information on how to change the location of these resources.

If you wish to use the GraphQL UI then please see the GraphQL MP Example.

Configuration

The specification defines the following configuration options:

The following configuration keys can be used to set up integration with WebServer:

The following configuration keys can be used to set up GraphQL invocation:

Examples

For a complete example, see GraphQL MP Example.

Additional Information

• GraphQL.

Reference

• MicroProfile GraphQL Javadocs.