Jakarta EE EclipseCon 2020, 23 Oct 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Boost your APIs with GraphQL

Description

When it comes to API, REST is king. Its simplicity and pragmatism have seduced the greatest number of people. Even if the good practices and recommendations of Roy Fielding, its founder, are not always well implemented…

In 2012, FaceBook developped GraphQL which is an alternative API technology based on a query language and an execution engine. Since then, GraphQL has become Open Source and is now managed under the umbrella of the Linux foundation. This presentation will allow you to understand the characteristics of GraphQL and how it relates to REST: complement or replacement? Is it just for unicorn or open to enterprise applications?

It will also be the opportunity to showcase a concrete implementation with MicroProfile GraphQL.

So, ready to boost your APIs?

Speaker(s):
Jean-François James (Worldline)

A

Okay, so thank you for coming to my presentation, which is about web apis in general and microprofile graphql in particular.

A

A few words about me: I am jean francois james. I've been working at oneline, the european leader in payment technology, I'm a software.

A

I started using java many years ago when it was young and trendy and despite its maturity. I believe that java has the power to renew itself and to stay relevant for a modern cloud native applications.

A

Two years ago I took the opportunity to contribute to an eclipse, open source project, microprofile graphql, and in doing so my ambition was to help promote the use of graphql by java applications.

A

The point is that graphql has grown in the javascript ecosystem, where it is identified as the variable solution. It's used by java applications remain confidential, even though it is a powerful and mature api technology.

A

I want this talk to be as pragmatic as possible and to provide you with just enough information to start your micro profile graphql journey, we'll start with a bit of history, about the origins of graphql, we'll make a high level comparison with rest.

A

We'll have an overview of micro profile and the focus on micro profile. Graphql will make a demo before having a conclusion.

A

So we welcome to the api economy. Apis are everywhere and we are surrounded by api driven applications and in that domain, in that domain, rest is king. It has been the de facto standard it has been widely adopted over the last decade and is backed by a strong ecosystem.

A

Rest takes its route from a doctoral dissertation written 20 years ago by roy felding, where it is defined as an architecture style. That means a set of constraints for web applications.

A

Graphql is more recent. It was born at facebook into co-created by lee byron, the smiling guy on the picture. It is a specification. It has been open source in 2015, adopted by github one year later and since 2018 it has been governed by a dedicated graphql foundation under the umbrella of the lunik linux foundation.

A

Comparing graphql with rest is a bit like comparing nosql with sql. There is no silver bullet and choosing the right solution depends on the use case and the context.

A

The core concept of rest is the resource, a resource being anything that can be named, for instance, a business entity or a business workflow. The core concept of graphql is the schema.

A

The schema defines both the data and how we can operate on them. It acts as a strongly typed contract between the api and its clients by construction. A rest application exposed several endpoints each being dedicated to a given operation. Action on a resource, in contrast, a graphql application expose a single generic queryable endpoint rest makes great use of http semantic leveraging its verb, verbs status, codes. Caching mechanism, graphql, is totally transport agnostic documenting a rest. Api requires an additional technology such as open api graphql has a built-in schema based documentation.

A

The graphql query language is very flexible and enables data selection per request. You ask for the exact data. You need multiple queries at a time in a single round trip network round trip and partial results.

A

This feature will be showcased during the demo.

A

Ease of use is a key characteristic of rest, but that doesn't mean that doing rest well is easy. Many so-called restful apis do not comply with the architecture, style and reifelding himself has often complained about that.

A

Richardson model differentiates four levels of maturity for rest, apis and the highest one. High parameter is relatively complex to implement and seldom used from that perspective. Graphql is easier to use, but what is rest graphql exactly? It is a specification.

A

The document is publicly available. It's pragmatic and easy to read, and this specification defines both a query language and a runtime to execute those queries.

A

The query language defines three types: three kinds of operations: query for read-only operations, mutations for write, read operations and subscription.

A

The runtime part describes in a very precise way how a graphql engine is expected to behave.

A

There is a reference implementation written in javascript, and you can find many other implementations complying with the specification in different languages such as java, php, go rest and so forth.

A

There are still some misunderstanding about graphql. Let's clarify two of them. First off graphql is not about databases. It's a way to talk to web apis, not databases. It is intended to sit on top of your business logic. Just as a rest, it's not about formal graph. It doesn't mandate you to model data in terms of nodes, edge, explicit relationships, it's about naturally interconnected data that make it super clear. The capabilities of the appeal.

A

While you know almost everything about graphql, let's switch to micro profile micro profile, is a platform to develop cloud native applications. At least this is my definition.

A

It is based on a set of specifications covering key aspects such as observability fault, tolerance, web apis configuration reactive messaging.

A

There are two kinds of specs: some are part of the core which is versioned and released in a consistent way. Others are so-called standalone specification and graphql is one of them.

A

Let's focus on microprofile graphql.

A

It started end of 2018 with nice people such as andy mcwright and adam anderson from ibm, philipp krueger from reddit boyantomic.

A

The founder and main contributor of speaker speaker is a graphql java framework that has greatly inspired our work and I was accompanied by jean-baptiste, a colleague from warline 2019 was relatively busy, even if not spectacular in terms of delivery. First, we had to turn our proposal into a specification.

A

Then we had to work on the three parts of the specifications: the programmatic api, the documentation and the technology compatibility kit. So it was a lot of work in the background before being able to release anything.

A

A first milestone has been released in may, graphql 1.0 has been released, was released in february 2020, and it is now available on quarkus, open liberty and wi-fi.

A

As far as I know, the development is ongoing on oracle, eliden and tommy.

A

Enough speaking, let's go for a demo, so the demo is based on two services. Merchant contract and payment scoring merchant contracts is about how current payments are accepted by merchants.

A

Payment scoring provides some business metrics about the payment activity per merchant. These two services are totally independent. They share nothing except a score id to retrieve the scores of a given merchant there. They both expose a rest and graphql api, and we are going to use swagger, ui and graphical to play around with them.

A

In reality, those two services should be developed and run on totally different systems. For this demo and for the sake of simplicity, they are developed and deployed. In the same way, the code is available on github so feel free to reuse it. It may be a good starting point.

A

It is available on open liberty and quarkus, and we are going to use both of them during the demo.

A

Let's switch to the demo part.

A

So we are going to start with the rest api using swagger ui on quarkus. Our two services are exposed merchant contract and payment scoring, and we can, for instance, get data for merchant one.

A

Let's run it here, it is.

A

We can see that merchant is a relatively complex object with multiple attributes, such as card schemes, list of contacts, payment channels, postal address and so on.

A

The coder that implement this endpoint is based on jack, crs and microprofile open api for the documentation.

A

First, we find the merchant by id and then we generate a json object containing both the merchant data and the atos link, and then we return the result, nothing very complex so far so good. But what? If a client is just interested in the card schemes with this endpoint, it has to retrieve the world merchant data.

A

This is what we call overfetching reading more data data than really needed. Of course, we could implement an endpoint, a dedicated endpoint that just returned the current at what.

A

Just won the contacts another one just won the payment channels and so on. This could quickly lead to endpoint proliferation, which is not maintainable. How does it work with graphql.

A

So this is graphical running on quarkus graphical is similar to swagger. It enables to play around with a graphql interface. We have two panels on the left, to edit query and on the right to read the result.

A

So this operation is a query that enables to retrieve the card schemes for merchant one. Let's run it as you can see, we have just the data. We need no more, no less.

A

And we can easily add other fields, business activity brand name again. We have just the data we.

A

Need how does it work at the code level very complex? As you can see, we have a find by id method which implements this query and this find by id method, retrieve the merchant by id and return. The result, that's it.

A

It is annotated with a specific query, on a annotation to indicate that this is a graphql query and we have optional description and name annotations for the documentation and this single method. Verizon method enables a lot of flexibility on the, but how does it work behind the scene?

A

We have a documentation explorer panel on the right, let's expand it that enables to navigate in the schema in a user-friendly way. We can deep dive in the query. The data type.

A

We also have mutation to create and delete merchant.

A

In fact, the schema is available at a given url schema dot graphql, we have a static representation of the schema, including all data and operation definitions. It's very similar to open api.

A

But we can do more with graphql.

A

With this query,.

A

We have a description of all queries and mutations. That means that the schema is itself queryable. This is what we call insert introspection, and this introspection capability provides a lot of flexibility on the client side to use the api and its documentation in a user-friendly.

A

Way, we can also ask for different data on for multiple queries at a time. In this case, we ask for different data for merchants, 1 and merchant 2.. Ok, so far we have not used our scoring service. Let's explore it using swagger ui on open liberty.

A

As we can see, this is a very basic service enabling to retrieve some business metrics.

A

According to merge score identifier,.

A

And with these apis with this, if we want to aggregate both merchant data and score data data, we need two calls the first one to read the merchandise, including the scroll id and the second one to read the score data. This is what we call under fetching. We do not have enough information in the first call and we need another call to have the world data we need.

A

How does it work with graphql? Let's switch to graphical this time on open liberty.

A

First, let's see the code, we have a get scores method that returns the list, of course, the list of scores for a merchant, nothing very complex. We check if the scoring service is enabled for that merchant and if, yes, we return the score.

A

As you can see, the merchant parameter is annotated with source, and this makes score data available to all merchants.

A

It extends the merchant graph graphql type by externally by an externally defined field, and this is the magic of graphql. How does it work on the client side very easily?

A

You can see that in the same request, we aggregate both the merchant data and the score data, but what if a read-on or another, the scoring service is not available. How does it work at the graphql level to simulate this?

A

I have implemented a very complex error on scores method which which serves the same signature as get scores and throw a runtime exception.

A

So to simulate this we we just have to replace scores by error and scores what happens in that case, we can see that there are two parts in the response.

A

The first, the first one indicates that an error has occurred while calling the scores- and the second one includes data coming from the merchant, because these that these data are available. This is what we call partial.

A

Results so far we have just read the data. We can also easily.

A

Modify them, let's create a merchant, we have created merchant 21 and we can as it as easily sorry delete it.

A

Here it is again the code that implements this mutation is very easy. We have a create merchant method, we which just call the underlying service to delete the merchants and the same form to create the merchant and the same for deleting it. Both methods are annotated with mutations.

A

By the way we can see here that microprofile graphql follow a code first approach. That means that the graphql schema is derived from the code.

A

An alternative approach is called the schema first approach when you design the schema up front using a specific dsl, and afterwards you develop specific classes that implements this schema.

A

The main benefit of the code first approach is that you have a single source of truth, which is the code you do not have to play with multiple artifacts.

A

So that's it for the demo. Let's go back to the presentation, so the presentation has been made with micro profile 1.0. This is a good starting point, but this is not the end of the story and we have plenty of improvements in the backlog.

A

We have defined two client apis, a high level, one based on java interfaces and very close to micro, profile, res client and a dynamic one close to the graphql query language.

A

Other areas of improvements are better integration with other microprofile specifications in particular matrix and jot. Pagination made easy for large data sets graphql context injection to make the server aware of the calling request fully aware of the calling request.

A

Graphql data, loader integration to optimize execution of complex query queries by introducing caching and batching mechanism, and why not a query cost analysis.

A

To wrap up graphql is a powerful api technology which is particularly relevant to expose rich data models. We also speak of data intensive api.

A

It enables to provide maximum flexibility on the client side, which can be a great benefit if you have different kind of client technology.

A

The client technologies is requiring its own specificities, so you can provide a lot of flexibility on the client side without suffering from the end point of proliferation, it's also very powerful to aggregate in a consistent way, different data sources and services.

A

What are the challenge to adopt a graphql in an organization? First, it is a new technology to introduce. It has to be agreed both on the client and server side. It is not a detail of implementation.

A

The schema has to be carefully designed. There is a risk of complex queries. In particular, if the schema expose cyclic dependencies and in production, it is recommended to protect against complex queries and to avoid those attacks.

A

The api management has to be revisited compared to compared to rest. It cannot be endpoint based. Remember that a graphql application exports a single endpoint. So if you want to introduce policies including traffic, limiting access right management, quality of service monetization, you need to do it at the graphql operation level.

A

Modern api solutions, such as w wso2 and tick, are graphql compliant. They support graphql and last but not least- and this was the purpose of my presentation- microprofile makes it easy for you to adopt.

A