MicroProfile GraphQL

THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of the copyright holders or the Eclipse Foundation may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

All number scalars (Int, Float, BigInteger and BigDecimal) can be formatted using the @NumberFormat or alternatively the JSON-B annotation @JsonbNumberFormat (except that @JsonbNumberFormat is not valid on TYPE_USE)

In the case that a property has both @NumberFormat and @JsonbNumberFormat, the GraphQL annotation (@NumberFormat) takes priority.

When formatting is added to a number type, the formatted result will be of type String. The type in the schema could be defined as String or another Custom Scalar to indicate the formatting.

Example:

will result in a formatted amount (South African Rand) in the result:

List example:

The formatting annotations can also be placed on a Query or Mutation that returns a number, example:

This will format the input and return the formatted result, example when executing with 345 as input number:

By default the date related scalars (DateTime, Date, and Time) will use an ISO-8601 format.

By adding the @DateFormat annotation, or alternatively JSON-B annotation @JsonbDateFormat, a user can change the format. However, @JsonbDateFormat does not support usage on TYPE_USE.

In the case that a property has both @DateFormat and @JsonbDateFormat, the GraphQL annotation (@DateFormat) takes priority.

When formatting is added to a date type, the formatted result will be of type String. The type in the schema could be defined as String or another Custom Scalar to indicate the formatting.

The formatting annotations can also be placed on a Query or Mutation that returns a date-like object, example:

This will format the input and return the formatted result:

GraphQL differentiates output types and input types. Input types are entities that are sent by the client as arguments to queries or mutations. Types are entities that are sent from the server to the client as return types from queries or mutations.

In many cases the same Java type can be used for input (sent from the client) and output (sent to the client), but there are cases where an application may need two different Java types to handle input and output.

The @Type annotation is used for output entities while the @Input annotation is used for input entities.

Normally these annotations are unnecessary if the type can be serialized and/or deserialized, and if the type is specified in a query or mutation method. These annotations can be used to specify the name of the type in the GraphQL schema; by default, the entity name in the schema will be the same as the simple class name of the entity type for output types; for input types, the simple class name is used with "Input" appended. Thus, an entity class named com.mypkg.Tree would create a GraphQL schema type called "Tree" and an input type called "TreeInput".

It is possible for output types to be defined as a Java interfaces. GraphQL interfaces are very similar in concept to Java interfaces, in that other types may implement an interface. This allows the GraphQL schema to better align with the Java application’s model and allows clients to retrieve the same data (fields) on multiple different entity types. GraphQL interfaces are created with a Java interface type and might be annotated with @Interface. The MP GraphQL implementation must then generate a schema where every class in the application that implements that Java interface must have a type in the schema that implements the GraphQL interface. For example:

This should generate a schema like:

Fields in GraphQL are similar to fields in Java in that they are a child of a single entity. Thus, Java fields on entity classes are, by default, GraphQL fields of that entity. It is also possible for GraphQL fields that are not part of the Java entity object to be represented as a field of the GraphQL entity. This is because all GraphQL fields are also queries.

Consider the following example:

The Java fields, name, realName and superPowers are all GraphQL fields of the SuperHero entity type. Now consider this example:

The above query adds a new field to the SuperHero GraphQL entity type, called currentLocation. This field is not part of the SuperHero Java class, but is part of the GraphQL entity. This association is made by using the @Source annotation. Also note that the currentLocation method will only be invoked if the client requests the currentLocation field in the query. This is a useful way to prevent looking up data on the server that the client is not interested in.

The Java code example above will add a field to the SuperHero type in the schema:

You can also choose to expose the method containing the @Source annotation as a top-level Query by adding the @Query annotation:

Above will create the field on SuperHero as described before, and will also add a Query like this:

GraphQL endpoints must be annotated with the @GraphQLApi annotation.

The @GraphQLApi annotation is a marker annotation that identifies a CDI Bean as a GraphQL Endpoint

For classes that are annotated with @GraphQLApi, implementations must create a query in the schema for every method that is annotated with @Query.

The query’s name can be specified in the value parameter of the @Query annotation, or is generated from the method name if no annotation value is provided.

Note that generic types other than subtypes of java.util.Collection (such as java.util.List or java.util.Set) are not allowed to be specified as query return types. Implementations may allow additional types (such as java.util.Map), but the behavior for these return types are undefined.

In the previous example, an explicitly defined query named "superHero" returns a SuperHero entity. The fields on that entity class are also implicitly defined as queries. It is possible to define fields as queries explicitly by using the @Source annotation on a parameter to the query method. More information on this is available in the Fields section.

The name of a query in the schema is obtained using the following order:

Note that it is considered a deployment error if more than one query method has the same name with the same arguments.

Queries may be documented with descriptions in the schema by adding a @Description annotation with documentation text as the annotation value to the query method. For example:

This would generate a schema that would include:

The @Description annotation can also be placed on parameters of a query method to provide documentation for the arguments. For example:

This would generate a schema that would include:

By it’s very nature, query methods must return some value, thus it is considered a deployment error for a method with a void return type to be annotated with @Query. If a void method is annotated with the @Query annotation, the implementation must prevent the application from starting and should provide a log message indicating that this is not allowed.

Like queries, mutation methods must be in a class annotated with the @GraphQLApi annotation.

Mutation methods are annotated with @Mutation. The name of the mutation is specified in the value of the annotation or is generated from the method name if no annotation value is provided.

Mutations generally require arguments (parameters) in order to determine which entity to modify/delete or the data necessary to create a new entity, etc. These arguments are the parameters of the mutation method and should (not mandatory) be annotated with @Name. The @Name annotation’s value is used to specify the name of the argument. The argument name will be used in the generated schema. Arguments can be GraphQL scalars, enums or more complex input types (for more information on input types, see Types vs Input).

Note that generic types other than subtypes of java.util.Collection (such as java.util.List or java.util.Set) are not allowed to be specified as mutation return types. Implementations may allow additional types (such as java.util.Map), but the behavior for these return types are undefined.

The name of a mutation in the schema is obtained using the following order:

Note that it is considered a deployment error if more than one mutation method has the same name with the same arguments.

As with Queries, Mutations may be documented with descriptions in the schema by adding a @Description annotation with documentation text as the annotation value to the mutation method. See the example in the Query section for more details.

Like query methods, mutation methods are expected to return some value, thus it is considered a deployment error for a method with a void return type to be annotated with @Mutation. If a void method is annotated with the @Mutation annotation, the implementation must prevent the application from starting and should provide a log message indicating that this is not allowed.

It is possible to specify a default value for query or mutation arguments so that the client does not need to specify a value. This is done via the @DefaultValue annotation. Read more about this in the Default Values section.

If an unchecked exception is thrown from the user application, the implementation must 'hide' the error message (for security reasons) and replace the message with a configured default message.

The default message is "Server Error" and can be configured by the user using MicroProfile Config and setting the mp.graphql.defaultErrorMessage property.

Example:

mp.graphql.defaultErrorMessage=Unexpected failure in the system. Jarvis is working to fix it.

Users can allow unchecked exception messages to be included (changing the default behavior as described above) by adding the exception class name to a whitelist. This is done using MicroProfile Config and setting the mp.graphql.exceptionsWhiteList property (comma-separated list)

Example:

mp.graphql.exceptionsWhiteList=org.eclipse.microprofile.graphql.tck.apps.superhero.api.WeaknessNotFoundException

By default checked exceptions must include the exception message in the message field of the error, and where possible also include the locations and path.

Implementations must support the ability to 'hide' this message for checked exceptions by allowing users to add them to a blacklist. This is done using MicroProfile Config and setting the mp.graphql.exceptionsBlackList property (comma-separated list)

Example:

mp.graphql.exceptionsBlackList=java.io.IOException,java.util.concurrent.TimeoutException