<commit_before>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= SmallRye GraphQL

include::./attributes.adoc[]

This guide demonstrates how your Quarkus application can use https://github.com/smallrye/smallrye-graphql/[SmallRye GraphQL],
an implementation of the https://github.com/eclipse/microprofile-graphql/[MicroProfile GraphQL] specification.

As the https://www.graphql.org/[GraphQL] specification website states:

[quote,]
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.
GraphQL provides a complete and understandable description of the data in your API,
gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time,
and enables powerful developer tools.

**GraphQL** was originally developed by **Facebook** in 2012 and has been
an open standard since 2015.

GraphQL is not a replacement for REST API specification but merely an
alternative. Unlike REST, GraphQL API's have the ability to benefit the client by:

Preventing Over-fetching and Under-fetching::
    REST API's are server-driven fixed data responses that cannot be determined by
    the client. Although the client does not require all the fields the client
    must retrieve all the data hence `Over-fetching`. A client may also require
    multiple REST API calls according to the first call (HATEOAS) to retrieve
    all the data that is required thereby `Under-fetching`.

API Evolution::
    Since GraphQL API's returns data that are requested by the client adding additional
    fields and capabilities to existing API will not create breaking changes to existing
    clients.

== Prerequisites

include::includes/devtools/prerequisites.adoc[]

== Architecture

In this guide, we build a simple GraphQL application that exposes a GraphQL API
at `/graphql`.

This example was inspired by a popular GraphQL API.

== Solution

We recommend that you follow the instructions in the next sections and create the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].

The solution is located in the `microprofile-graphql-quickstart` {quickstarts-tree-url}/microprofile-graphql-quickstart[directory].

== Creating the Maven Project

First, we need a new project. Create a new project with the following command:

:create-app-artifact-id: microprofile-graphql-quickstart
:create-app-extensions: graphql
include::includes/devtools/create-app.adoc[]

This command generates a project, importing the `smallrye-graphql` extension.

If you already have your Quarkus project configured, you can add the `smallrye-graphql` extension
to your project by running the following command in your project base directory:

:add-extension-extensions: graphql
include::includes/devtools/extension-add.adoc[]

This will add the following to your build file:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-graphql</artifactId>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("io.quarkus:quarkus-smallrye-graphql")
----<commit_msg>Update smallrye-graphql.adoc<commit_after>////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= SmallRye GraphQL

include::./attributes.adoc[]

This guide demonstrates how your Quarkus application can use https://github.com/smallrye/smallrye-graphql/[SmallRye GraphQL],
an implementation of the https://github.com/eclipse/microprofile-graphql/[MicroProfile GraphQL] specification.

As the https://www.graphql.org/[GraphQL] specification website states:

[quote,]
GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data.
GraphQL provides a complete and understandable description of the data in your API,
gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time,
and enables powerful developer tools.

**GraphQL** was originally developed by **Facebook** in 2012 and has been
an open standard since 2015.

GraphQL is not a replacement for REST API specification but merely an
alternative. Unlike REST, GraphQL API's have the ability to benefit the client by:

Preventing Over-fetching and Under-fetching::
    REST API's are server-driven fixed data responses that cannot be determined by
    the client. Although the client does not require all the fields the client
    must retrieve all the data hence `Over-fetching`. A client may also require
    multiple REST API calls according to the first call (HATEOAS) to retrieve
    all the data that is required thereby `Under-fetching`.

API Evolution::
    Since GraphQL API's returns data that are requested by the client adding additional
    fields and capabilities to existing API will not create breaking changes to existing
    clients.

== Prerequisites

include::includes/devtools/prerequisites.adoc[]

== Architecture

In this guide, we build a simple GraphQL application that exposes a GraphQL API
at `/graphql`.

This example was inspired by a popular GraphQL API.

== Solution

We recommend that you follow the instructions in the next sections and create the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].

The solution is located in the `microprofile-graphql-quickstart` {quickstarts-tree-url}/microprofile-graphql-quickstart[directory].

== Creating the Maven Project

First, we need a new project. Create a new project with the following command:

:create-app-artifact-id: microprofile-graphql-quickstart
:create-app-extensions: quarkus-smallrye-graphql
include::includes/devtools/create-app.adoc[]

This command generates a project, importing the `smallrye-graphql` extension.

If you already have your Quarkus project configured, you can add the `smallrye-graphql` extension
to your project by running the following command in your project base directory:

:add-extension-extensions: quarkus-smallrye-graphql
include::includes/devtools/extension-add.adoc[]

This will add the following to your build file:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-graphql</artifactId>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("io.quarkus:quarkus-smallrye-graphql")
----
{'fraction_non_alphanumeric': 0.07941722611055564, 'fraction_numerical': 0.0022853878017426083, 'mean_word_length': 4.739344262295082, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 8, 'lorem ipsum': 0, 'www.': 2, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5661293', 'n_tokens_mistral': 1968, 'n_tokens_neox': 1844, 'n_words': 789}