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 specified fields for an object or collection of 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
@org.eclipse.microprofile.graphql.GraphQLApi
public class ContactGraphQLApi {

    @Inject
    private CustomerService customerService;

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

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

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

    @org.eclipse.microprofile.graphql.Mutation
    public Contact 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 Customers
• a query that takes an argument to return a specific Customer
• a query that optionally takes a name and returns a collection of Customers
• a mutation that creates a Customer and returns the newly created Customer

The 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 URL’s described below.

As per the instructions here ensure you have added a src/main/resources/META-INF/beans.xml file, so the CDI implementation can pick up your classes.

A Main class is not needed, you can configure io.helidon.microprofile.cdi.Main as the entry point.

Optionally, you can configure a custom entry point (such as when you need custom configuration setup).

public class MyMain {
    public static void main(String[] args) {
        io.helidon.microprofile.cdi.Main.main(args);
    }
}

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

<plugin>
<groupId>org.jboss.jandex</groupId>
<artifactId>jandex-maven-plugin</artifactId>
<executions>
  <execution>
    <id>make-index</id>
  </execution>
</executions>
</plugin>

The specification defines the following configuration options:

These configuration options are more significant that the configuration options that can be used to configure GraphQL invocation (see below).

In addition, we provide 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: