mp.graphql.adoc Maven / Gradle / Ivy

Go to download
///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2019, 2024 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

= MicroProfile GraphQL
:description: Helidon GraphQL MicroProfile
:keywords: helidon, graphql, microprofile, micro-profile
:feature-name: MicroProfile GraphQL
:rootdir: {docdir}/..
:microprofile-bundle: false

include::{rootdir}/includes/mp.adoc[]

== Contents

- <>
- <>
- <>
- <>
- <>
- <>
- <>

== Overview

Helidon MP implements the
link:{microprofile-graphql-spec-url}[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.


include::{rootdir}/includes/dependencies.adoc[]

[source,xml]
----

    io.helidon.microprofile.graphql
    helidon-microprofile-graphql-server

----

== 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.

[source,java]
.Simple ContactGraphQLApi
----
include::{sourcedir}/mp/GraphqlSnippets.java[tag=snippet_1, indent=0]
----

<1> a query with no-arguments that will return all `Customer` s
<2> a query that takes an argument to return a specific `Customer`
<3> a query that optionally takes a name and returns a collection of `Customer` s
<4> a mutation that creates a Customer and returns the newly created `Customer`

The example above would generate a GraphQL schema as shown below:
[source,graphql]
.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.

[source,xml]
.Generate Jandex index
----

    io.smallrye
    jandex-maven-plugin
    
        
            make-index
        
    

----

NOTE: As per the instructions xref:introduction/microprofile.adoc[here] ensure you have added a
`src/main/resources/META-INF/beans.xml` file, so the CDI implementation can pick up your classes.

=== 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 <> for
additional information on how to change the location of these resources.

If you wish to use the
link:https://github.com/graphql/graphiql[GraphQL UI] then please see the
link:{helidon-github-tree-url}/examples/microprofile/graphql[GraphQL MP Example].

== Configuration

The specification defines the following configuration options:

[cols="2,2,5"]

|===
|key |default value |description

|`mp.graphql.defaultErrorMessage` |`Server Error` |Error message to send to caller in case of error
|`mp.graphql.exceptionsBlackList` |{nbsp} |Array of checked exception classes that should return default error message
|`mp.graphql.exceptionsWhiteList` |{nbsp} |Array of unchecked exception classes that should return message to caller (instead of default error message)

|===

include::{rootdir}/includes/graphql.adoc[]

== Examples

For a complete example, see
link:{helidon-github-tree-url}/examples/microprofile/graphql[GraphQL MP Example].

== Additional Information

 * link:http://graphql.org[GraphQL].

== Reference

 * link:{microprofile-graphql-javadoc-url}[MicroProfile GraphQL Javadocs].