[Chapter 12 - MicroProfile GraphQL 2.0] Add new chapter about MicroProfile GraphQL 2.0 by ttelang · Pull Request #68 · microprofile/microprofile-tutorial

ttelang · 2026-03-31T16:42:45Z

This chapter introduces MicroProfile GraphQL 2.0, covering its features, advantages over REST, and how to implement GraphQL APIs in Jakarta EE and MicroProfile applications.

It covers the following topics:

What is GraphQL and key differences from REST
Schema-first and Code-first approaches
Project Dependencies (Maven and Gradle)
Defining GraphQL service endpoints
Annotations for defining GraphQL operations and metadata
Scalar types, enumerations, and GraphQL interfaces
Custom Object Mapping and Field Resolution
Error Handling and Partial Results
Integration with MicroProfile Config

This chapter introduces MicroProfile GraphQL 2.0, covering its features, advantages over REST, and how to implement GraphQL APIs in Jakarta EE and MicroProfile applications. It includes topics such as defining endpoints, using annotations, error handling, and project dependencies.

t1

Great work! I wouldn't say that and add all this nitpicking comments, if I thought differently ;-)

t1 · 2026-05-27T07:49:55Z

+
+== Introduction
+
+APIs serve diverse clients including mobile applications,single-page web apps, and third-party services, each with different data requirements. REST APIs either return more data than the client needs (over-fetching) or too little, forcing multiple round trips to assemble a complete response (under-fetching). GraphQL eliminates both problems by shifting query control to the client, allowing callers to declare exactly the fields and relationships they need in a single request.


Technology selection is not the main driver behind that diversity: different clients have unforeseen use-cases that need different parts of an api.

And I assume that it's hard for people to really understand over-/under-fetching from this description alone. I would expand on it in the Data Fetching section and link forward from here.

I would also add: But also the service can see, what clients actually use, down to the field, allowing to safely remove unused features.

And something about the @Source resolver mechanism. I think this is absolutely essential to appreciate the power of GraphQL in Java.

t1 · 2026-05-27T08:41:31Z

+
+== What is GraphQL?
+
+GraphQL is a query language for APIs and a runtime for executing those queries against a type system you define for your data. It was developed by Facebook in 2012 and open-sourced in 2015. 


I would add: It's often received as a technology for frontends, but it's equally helpful for machine-to-machine communication.

t1 · 2026-05-27T08:42:13Z

+
+GraphQL is a query language for APIs and a runtime for executing those queries against a type system you define for your data. It was developed by Facebook in 2012 and open-sourced in 2015. 
+
+GraphQL is self-describing: the schema that powers an API also serves as its documentation, enabling powerful developer tooling and making APIs easier to evolve without versioning.


I would add: It's like OpenAPI and Swagger was already built-in.

t1 · 2026-05-27T08:44:26Z

+
+GraphQL is self-describing: the schema that powers an API also serves as its documentation, enabling powerful developer tooling and making APIs easier to evolve without versioning.
+
+A GraphQL service exposes a strongly typed schema that declares every type, field, and operation available. Clients construct queries that mirror the shape of the data they need, and the server responds with exactly that structure. This schema-first contract gives both client and server teams a shared, unambiguous definition of the API surface.


I wouldn't use "schema-first" here, as that's a different aspect. Just "This contract gives..."

t1 · 2026-05-27T08:51:10Z

+
+* *Code-First Development*: Define GraphQL schemas using Java annotations on POJOs and methods, eliminating the need to author or maintain a separate schema file
+* *CDI Integration*: Seamless integration with Jakarta Contexts and Dependency Injection for lifecycle management and service injection
+* *Type Safety*: Java's type system drives schema generation, catching structural errors at compile time rather than at runtime


I would already add here something like: At the same time, resolvers allow for on-demand extension of the schema (see below).

with a link to the Using @Source to Resolve Nested Types section

t1 · 2026-05-27T09:13:03Z

+}
+----
+
+Most MicroProfile implementations also provide a GraphiQL or GraphQL Playground interface for interactive exploration, typically accessible at `/graphql-ui` or `/graphiql`.


Suggested change

Most MicroProfile implementations also provide a GraphiQL or GraphQL Playground interface for interactive exploration, typically accessible at `/graphql-ui` or `/graphiql`.

Most MicroProfile implementations also provide a GraphiQL or GraphQL Playground interface for interactive exploration (think Swagger), typically accessible at `/graphql-ui` or `/graphiql`. You can also use external tools to interactively explore a GraphQL API.

t1 · 2026-05-27T09:20:15Z

+}
+----
+
+The `@NonNull` annotation indicates that a field cannot be null, which translates to the `!` operator in GraphQL schema:


show the import for @NonNull; there are too many

t1 · 2026-05-27T09:22:28Z

+
+=== Defining GraphQL Interfaces with @Interface
+
+Use the `@Interface` annotation on a Java interface to define a GraphQL interface type. The MicroProfile GraphQL implementation generates a GraphQL interface in the schema for every class in the application that implements the annotated Java interface:


Suggested change

Use the `@Interface` annotation on a Java interface to define a GraphQL interface type. The MicroProfile GraphQL implementation generates a GraphQL interface in the schema for every class in the application that implements the annotated Java interface:

Use the `@Interface` annotation on a Java interface to define a GraphQL interface type. The MicroProfile GraphQL implementation generates a GraphQL interface in the schema and a GraphQL type for every class in the application that implements the annotated Java interface:

t1 · 2026-05-27T09:37:38Z

+
+== Integration with MicroProfile Config
+
+MicroProfile GraphQL integrates with MicroProfile Config, allowing you to externalize configuration for your GraphQL services. This is particularly useful for controlling error message visibility across environmentsfor example, exposing detailed messages in development while suppressing them in production.


Suggested change

MicroProfile GraphQL integrates with MicroProfile Config, allowing you to externalize configuration for your GraphQL services. This is particularly useful for controlling error message visibility across environmentsfor example, exposing detailed messages in development while suppressing them in production.

MicroProfile GraphQL integrates with MicroProfile Config, allowing you to externalize configuration for your GraphQL services. This is particularly useful for controlling error message visibility across environments, for example, exposing detailed messages in development while suppressing them in production.

t1 · 2026-05-27T09:41:48Z

+
+=== Query Naming and Descriptions - @Name, @Description, @DefaultValue
+
+Use `@Name` to specify the name of a field or parameter in the GraphQL schema:


I would add that the parameter name in the source code is the default, but this requires setting compiler options (explain which ones)

ttelang marked this pull request as ready for review March 31, 2026 16:43

ttelang mentioned this pull request Mar 31, 2026

Update MicroProfile Tutorial to MP 7.1 microprofile/microprofile-marketing#1104

Open

ttelang changed the title ~~Add chapter on MicroProfile GraphQL 2.0~~ [Chapter 11 - MicroProfile GraphQL 2.0] Add new chapter about MicroProfile GraphQL 2.0 Apr 7, 2026

ttelang changed the title ~~[Chapter 11 - MicroProfile GraphQL 2.0] Add new chapter about MicroProfile GraphQL 2.0~~ [Chapter 12 - MicroProfile GraphQL 2.0] Add new chapter about MicroProfile GraphQL 2.0 Apr 7, 2026

ttelang mentioned this pull request May 19, 2026

Request for Review: GraphQL Chapter in MicroProfile 7.1 API Tutorial PR#68 and PR#74 microprofile/microprofile-graphql#594

Open

t1 reviewed May 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Chapter 12 - MicroProfile GraphQL 2.0] Add new chapter about MicroProfile GraphQL 2.0#68

[Chapter 12 - MicroProfile GraphQL 2.0] Add new chapter about MicroProfile GraphQL 2.0#68
ttelang wants to merge 1 commit into
microprofile:mainfrom
ttelang:mp-graphql-2.0

ttelang commented Mar 31, 2026

Uh oh!

t1 left a comment

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

t1 May 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		== Introduction

		APIs serve diverse clients including mobile applications,single-page web apps, and third-party services, each with different data requirements. REST APIs either return more data than the client needs (over-fetching) or too little, forcing multiple round trips to assemble a complete response (under-fetching). GraphQL eliminates both problems by shifting query control to the client, allowing callers to declare exactly the fields and relationships they need in a single request.


		== What is GraphQL?

		GraphQL is a query language for APIs and a runtime for executing those queries against a type system you define for your data. It was developed by Facebook in 2012 and open-sourced in 2015.


		GraphQL is a query language for APIs and a runtime for executing those queries against a type system you define for your data. It was developed by Facebook in 2012 and open-sourced in 2015.

		GraphQL is self-describing: the schema that powers an API also serves as its documentation, enabling powerful developer tooling and making APIs easier to evolve without versioning.


		GraphQL is self-describing: the schema that powers an API also serves as its documentation, enabling powerful developer tooling and making APIs easier to evolve without versioning.

		A GraphQL service exposes a strongly typed schema that declares every type, field, and operation available. Clients construct queries that mirror the shape of the data they need, and the server responds with exactly that structure. This schema-first contract gives both client and server teams a shared, unambiguous definition of the API surface.

	Most MicroProfile implementations also provide a GraphiQL or GraphQL Playground interface for interactive exploration, typically accessible at `/graphql-ui` or `/graphiql`.
	Most MicroProfile implementations also provide a GraphiQL or GraphQL Playground interface for interactive exploration (think Swagger), typically accessible at `/graphql-ui` or `/graphiql`. You can also use external tools to interactively explore a GraphQL API.


		=== Defining GraphQL Interfaces with @Interface

		Use the `@Interface` annotation on a Java interface to define a GraphQL interface type. The MicroProfile GraphQL implementation generates a GraphQL interface in the schema for every class in the application that implements the annotated Java interface:


		== Integration with MicroProfile Config

		MicroProfile GraphQL integrates with MicroProfile Config, allowing you to externalize configuration for your GraphQL services. This is particularly useful for controlling error message visibility across environmentsfor example, exposing detailed messages in development while suppressing them in production.


		=== Query Naming and Descriptions - @Name, @Description, @DefaultValue

		Use `@Name` to specify the name of a field or parameter in the GraphQL schema:

Conversation

ttelang commented Mar 31, 2026

Uh oh!

t1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants