• Overview

• Maven Coordinates

• API

• Configuration

• Examples

• Additional Information

• Reference

Helidon MP implements the MicroProfile GraphQL specification. This specifcation 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.

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>

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.

@ApplicationScoped
@GraphQLApi
public class ContactGraphQLApi {

    @Inject
    private CustomerService customerService;

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

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

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

    @Mutation
    public Customer createCustomer(@Name("customerId") int id, 
                                  @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
}

• a query with no-arguments that will return all Customer s
• a query that takes an argument to return a specific Customer
• a query that optionally takes a name and returns a collection of Customer s
• a mutation that creates a Customer and returns the newly created Customer

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

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

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

Accessing the GraphQL endpoints

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:

For a complete example, see GraphQL MP Example.

• GraphQL.

• MicroProfile GraphQL Javadocs.