qaware.de
How to provide a GraphQL API - I want it that way!
Stefan Schmöller, QAware GmbH

Stefan Schmöller
Senior Software Engineer @ QAware GmbH

Agenda
Why GraphQL?
The Server Side: Writing a GraphQL API layer by hand
The Client Side: Consuming a GraphQL API using Quarkus
Conclusion and Q&A

What is it?
Query Language for APIs
and runtime to fulfill this queries
with existing data
Why do we want it?
Clients can dynamically define
the structure of required data,
which is then returned by the
server.
Over-fetching and under-fetching
are history!
Does it work?
Stay tuned :)
https://graphql.org/

Ask for what you want:
No more under-fetching or over-fetching
sessionId
sessionTitle
speakerLastName
sessionId
sessionTitle
firstName
lastName
currentLocation
phone
/sessions
/speakers/{speaker-id}
/schedule
Use Case 1:
● aggregate
● select only relevant attributes
● rename

Ask for what you want:
No more under-fetching or over-fetching
sessionId
sessionTitle
speakerLastName
sessionId
sessionTitle
firstName
lastName
currentLocation
phone
/full-schedule
/schedule-for-my-use-case
dateOfBirth
favoriteDish
shoeSize
Use Case 2:
● select only relevant attributes of
large API

Send your query - get your response

Send your query - get your response

The Developer Way
Writing a GraphQL API layer by hand

“The Developer Way”: Directly offering a GraphQL API using Quarkus
■ Initial situation: two seperate APIs for sessions and speakers at the conference
■ Idea: We implement a GraphQL-Endpoint providing and combining all the information
GET /sessions
[{
id: 1
title: “abc”
speaker: [1,2]
…
}]
GET /sessions/{id}
…
GET /speakers
[{
id: 1
firstName: “Bill”
lastName: “Gates”
…
}]
GET /speakers/{id}
…
GET
/sessions/speaker/{id}
[{
title:
…
}]

Summary: How to provide a GraphQL endpoint with Quarkus
■ Create a resource annotated with @GraphQLApi
■ Methods annotated with @Query(value=”...”) (or @Mutation) are made available at endpoint
– If value is specified, this is the name of the query (mutation)
– Otherwise the name of the method is used (get… will be removed)
– Schema is built using the Java Objects
■ @Description can be used to add a descriptive text
■ Types can be extended using @Source in methods
– Annotated Input parameter marks the type to be extended
– Extension happens automatically
– Return type defines what to add
■ Important application paths:
– /graphql → Application endpoint for GraphQL queries (can be changed via property)
– /graphql/schema.graphql → Request current schema
– /q/graphql-ui/ → GraphiQL UI for testing requests

The Client Side
Consuming a GraphQL API using Quarkus

The client side: Consuming a GraphQL service using Quarkus
■ Two different implementation variants:
– Dynamic
• Building the query with a fluent API
• Client returns a JsonObject of the GraphQL response
@Inject @GraphQLClient("ec-dynamic")
DynamicGraphQLClient client;
@GET @Path("sessions")
public Uni<JsonObject> getSessions() {
Document query = document(operation(
field("sessions",
field("startTime"),
field("title"),
field("speaker",
field("fullName")
)
)
));
return client.executeAsync(query).map(Response::getData);
}

The client side: Consuming a GraphQL service using Quarkus
■ Two different implementation variants:
– Typesafe
• Define the DTOs and let Quarkus do the rest
• DTOs are related via Query name and GraphQL schema
• Annotations can be used for name mapping
public class EngineeringCampTypesafeResource {
@Inject
EngineeringCampTypesafeClient client;
@GET @Path("sessions")
public Uni<List<Session>> getSessions() {
return client.getAllSessions();
}
}
@GraphQLClientApi(configKey = "ec-typesafe")
public interface EngineeringCampTypesafeClient {
@Query(value = "sessions")
Uni<List<Session>> getAllSessions();
}

qaware.de
QAware GmbH
Aschauer Straße 32
81549 München
Tel. +49 89 232315-0
info@qaware.de
twitter.com/qaware
linkedin.com/company/qaware-gmbh
xing.com/companies/qawaregmbh
slideshare.net/qaware
github.com/qaware
Conclusion and Q&A