DEV Community: imphilippesimo

Testing your GraphQL APIs in a Spring-boot app

imphilippesimo — Sat, 13 Jun 2020 16:57:43 +0000

This article is the fourth article of the series GraphQL, from theory to real-world with Spring-boot. But don’t worry, The stories are designed to be consumed independently from the other stories. You just have to grab the current state of the project by doing this:

git clone -n https://github.com/zero-filtre/springboot-graphql-error-handling.git && cd springboot-graphql-error-handling

git checkout 71d5f771bf9a6feaf8a5b7f62947442aace2b127
git switch -c my_experimental_branch

In this article, we will see how we can test the resources that we have defined in the project.

You can check out the corresponding video here:

We want to make sure the tests are fast, reliable and easy to understand.

If you have not cloned our project, then you may need these dependencies in your pom.xml

<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-spring-boot-starter-test</artifactId>
    <version>6.0.0</version>
    <scope>test</scope>
</dependency>

We have three resources to test, we will then define three GraphQL queries to load from our resources folder.

If it’s not already done, create this directory in your project:

src/test/resources/graphql then create these 3 request file in it.

mutation{
    createUser(username: "johndoe",password: "mypassword"){
        id
        username
    }
}

create-user.graphql

mutation{
    deleteUser(username: "johndoe"){
        id
        username
    }
}

delete-user.graphql

query{
    getUser(username: "johndoe",password: "mypassword"){
        id
        username
    }
}

get-user.graphql

In our test package we will create 2 classes :
One for testing mutations and another one to test queries.

UserMutationIntTest.java

Let’s dissect what is happening here.

We want to test the write requests: AKA the Mutation resolvers.

As we are using graphql-spring-boot-starter-testwe are taking advantage of the embedded JUnit 5 Jupiter engine, and some useful tools to set up graphql easily.

Especially the @GraphQLTestannotation that is loading only a slice of the Spring-context that is needed for our tests to run.

This is particularly interesting as our tests need to run fast and not wait for the full heavy Spring context to load.

Another interesting tool is the GraphQLTestTemplate class that helps us send real GraphQL queries, that we have defined earlier, to tests our resolvers.

As we want our tests to run as fast as possible, we do not need to load the real underlying beans needed for our resolvers, talking here about the UserService bean. We will just mock them, and tell the mock how to behave when a specific method is called by the resolver.

Finally, as we have secured our GraphQL resources, we have to use Spring-security to mock users with adequate rights.

We are following the same logic for testing the read request resolvers, AKA : Query resolvers

UserQueryIntTest.java

And that’s all you have to do to test that your resolvers are responding to the requests you expect them to.

This is the end of the series, I hope you enjoyed it.

Thanks for reading.

Feedback is a gift 🎁.

Secure your GraphQL API within a Spring-Boot App

imphilippesimo — Sat, 13 Jun 2020 16:56:57 +0000

This is the third episode of the series GraphQL, from Theory to Real-World with Spring boot. The episodes are designed to be consumed independently, so feel free to start from what interest ou the most.

Overview

In the previous article, we’ve exposed a set of resources via a GraphQL API. Now we want to secure them to prevent unauthenticated and unauthorized access.

TL;DR

Check the corresponding video.

NOTE: Reading the previous article IS NOT mandatory, they are designed to be consumed independently by just checking out the codebase on GitHub.

Spring security offers us the WebSecurityConfigurerAdapter::configure method to configure our app security. It gives us a way to define the access level of some resources based on URLs. Unfortunately, this is not a mechanism that fits well with the GraphQL protocol as it does with REST APIs.

Actually, graphQL is using only one endpoint, usually /graphql. Hence we cannot secure our resources based on URLs. As we want some resources to be either accessed only by administrators, or by authenticated users or even opened to the public.

But it becomes possible if we use annotations on resolvers methods, coupled with Aspect-Oriented Programming (AOP), and that’s what we are going to do.

So, at the end of this article, you will know how to:

Set up an aspect with Spring AOP,
Use aspect-oriented programming coupled with custom annotations to secure your resources,
Write tests to check your GraphQL API

Project Setup

Clone the code base that we had in the previous article:

git clone -n https://github.com/zero-filtre/springboot-graphql-error-handling.git && cd springboot-graphql-error-handling/

git checkout bd7a0b5c039c610de9c8355be0d1c5f5e5484655

git switch -c my_experimental_branch

We will make the resources:
createUser(username:string, password:string) public,

getUser(username:string, password:string) available for authenticated users only, and we will create an additional resource:

deleteUser(username:string), to be available for admin users only.

Add the following dependencies to the pom.xml

...
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-aspects</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.security</groupId>
  <artifactId>spring-security-test</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <scope>test</scope>
</dependency>
...

Then we add the additional deleteUser resource which matches the following resolver method in UserMutation.java:

public User deleteUser(String username) {
   return userService.deleteUser(username);
}

Don’t forget to define the UserService::delete method, which just removes the user corresponding to that username from the in-memory List<User> users and returns information about the deleted user.

Add deleteUser resource spec to the schema definition file: src/main/resources/UserQL.graphqls :

type Mutation {
    ...
    deleteUser(username: String!): User
}

Securing the resources

The strategy consists of:

Authorizing all requests related to GraphQL: /graphql
Then, thanks to custom annotations, specify, at the method level in resolvers, which methods are public, which ones should be accessed only by authenticated users, and which ones should only be accessed by users with specific roles such as ADMIN.
Whilst with aspects, we will check if our annotations are applied or not and throw exceptions accordingly.

Let’s create the security configuration file: SecurityConfig.java

This config tells our app to authorize all requests related to GraphQL so that we can check them at the resolver level with annotations.

We will have two annotations:
@AdminSecured appended to admin resources, and
@Unsecured appended to public resources.
All other endpoints will, by default, need authenticated users access.
It’s always better to forget to make a resource unsecured than to forget to secure it 😁

AdminSecured.java

*/**
 * This annotation will trigger Admin security check for
 * the GraphQL resolver method where it is marked.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface AdminSecured {}

Unsecured.java

*/**
 * This annotation will disable security check for
 * the GraphQL resolver method where it is marked.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Unsecured {}

Now go on and annotate the resolver methods accordingly:

@Unsecured
public User createUser(String username, String password) {
    return userService.createUser(username, password);
}

@AdminSecured
public User deleteUser(String username) {
    return userService.deleteUser(username);
}

UserQuery::getUser will be set as secured by default.

Let’s define the aspect that will scan these annotations.
First, we need to Enable AOP in the main application class,
by adding @EnableAspectJAutoProxy annotation like so:

@SpringBootApplication
@EnableAspectJAutoProxy
public class SampleGraphqlErrorHandlingApplication {
    public static void main(String[] args) {        SpringApplication.run(SampleGraphqlErrorHandlingApplication.class, args);
    }
}

Then the aspect class… But wait! ☝, What’s an aspect? 🤔

Aspects are related to Aspect-Oriented Programming (AOP) which gives you a way to encapsulate or modularize a behavior that is transversal and repeated across several types of objects and that is, normally, not easy to encapsulate in its own module.

Usually, those behaviors (logging, caching, transaction management…) are not related to business logic and they are so-called aspects.

An aspect is a common feature that’s typically scattered across methods, classes, object hierarchies, or even entire object models [3] .

Example:
AOP provides you with programmatic control to specify that you want calls:

To all methods annotated @Timed to trigger a timer before executing the actual body of that code,
To all methods classes in the package xxx.bank.account to trigger a specific additional security check,
etc

Without repeating yourself 😎

We are going to do something similar with our Aspect.

Yes, you have guessed it right, our aspect is about security check based on annotations.

SecurityGraphQLAspect.java

Don’t worry, It seems complicated but it’s actually pretty simple.
Let’s go through each part of it to understand what it’s being done here.

First, As we defined this spring component as @Aspect, it becomes an interceptor and we want it to be the first to be triggered, before any other interceptor, since it is our security guarantor. That’s why we use @Order(1)

The first method doSecurityCheckis annotated with @Beforewhich is an Advice, which means, according to AOP terminology: action taken by the aspect at a specific point during the execution of the program.

The @Before advice lets the action being executed before the specified PointCuts, which helps to categorize elements of the program that the aspect will watch.

doSecurityCheckis executed before all GraphQL resolvers methods that are defined within our project and that are not annotated as unsecured. These categories are then defined with the help of @PointCut.

doSecurityCheckchecks the Spring security context to make sure the user is authenticated.

Similarly: doAdminSecurityCheck is executed before *all methods annotated as AdminSecured. *

doAdminSecurityCheckchecks the Spring security context to make sure the user has the ADMIN role.

This is the code for the referenced UnauthenticatedAccessException.java:

public class UnauthenticatedAccessException extends RuntimeException implements GraphQLError {

    public UnauthenticatedAccessException(String msg) {
        super(msg);
    }

    @Override
    public List<SourceLocation> getLocations() { return null; }

    @Override
    public ErrorClassification getErrorType() { return null; }
}

That’s it! 🏁

Now let’s start the app, launch http://locahost:8080/graphiql and:

Create a user:

Everything works as expected ✌🏾.

Delete that user:

We do not have the right to do that as expected ✌🏾.

Get users:

We need to log in first as expected ✌🏾.

Let’s test the remaining cases programmatically so that you can automate it in a pipeline and earn some time.

GraphQLSecurityTests.java

Notice that we restart the context after each test method with @DirtiesContext to make sure every method runs in a clean, not polluted context. But you should not abuse this, as it increases considerably your tests execution time.
Run the test and should have a 100% success.

Now our endpoints are secured 😎.

Conclusion

GraphQL APIs are great but are different in so many ways from REST APIs, and the way to handle the security is no exception.

That’s why in this article, we saw how to use aspect-oriented programming coupled with custom annotations to secure our resources. Additionally, we also wrote tests to check the whole stuff.

I hope you enjoyed it.

In the next article, we will describe a strategy and apply a strategy to write fast, bulletproof tests for your GraphQL APIs with Spring boot.

Don’t forget, Feedback is a gift 🎁!

References:

[1]https://docs.spring.io/spring/docs/2.0.x/reference/aop.html

[2]https://mi3o.com/spring-graphql-security/

[3]https://docs.jboss.org/aop/1.0/aspect-framework/userguide/en/html/what.html

Understanding GraphQL Error Handling mechanisms in Spring-boot

imphilippesimo — Sat, 13 Jun 2020 16:53:11 +0000

Overview

This article is the second part of the series GraphQL, from Theory to real-world with Spring boot.

Today’s episode is about setting up your Spring-boot project to host your first GraphQL API entry points then call them using the web-based tool GraphiQL.

It also aims to bring an in-depth understanding of how the Graphql Java Implementation (graphql-java) deals with error handling and especially how to rely on that, by using the GraphQL Spring Framework boot starter, to handle efficiently errors within our app, as this is an aspect that is often overlooked by early graphql adopters.

TL;DR

Check the corresponding video out:

Before we start, let’s introduce some context.

GraphQL quick summary

GraphQL is a specification that defines not only a new query language for APIs but also how data is returned in response to these queries.
It is an alternative to using Restful APIs in the sense that it solves some of their drawbacks with new features such as these described ones:

The client has full control over the data returned to him, he receives only what he needs, no more, no less. No unnecessary data is therefore loaded onto the network. No over-etching.
The client can request several resources at once in a single request, no need to send multiple requests. Ideal for slow mobile connections.
The server defines what is possible or not with the notion of types, to force the client to request only what is possible.

With great power comes great responsibilities

According to the features mentioned above, the client must be highly considered when setting up such an API.

It is more than important to return a response format that is consistent and predictable across several scenarios, to make it easier for the customer to consume the response.

According to the specification, a GraphQL response should follow this pattern:

A GraphQL response might always have the HTTP status 200 OK.

HTTP error codes are not relevant when using GraphQL because,
If a request fails, the JSON payload of the server’s response will contain a root field called “errors” that contains precise information about the problems that occurred on the server-side.

Moreover, since GraphQL allows for multiple operations to be sent in the same request, well, it’s possible that a request fails partially and returns actual data and errors.

The response body could contain the following fields:
“data”: where the data resulting from the operation reside.
“errors”: where all the errors are filled in.
“extensions”: for additional information about the response

The "errors" field, should contain the following fields :
"message": a key describing the error
"locations": a list of graph coordinates where the errors have occurred.
"path": a key describing the absolute path from the root of the graph to the field where an error has occurred.
"extensions" key for the metadata related to the errors.

You can learn more about GraphQL response format by referring to the specification part that deals with this topic.

As far as we are concerned, we will just focus on the "errors" key.

By relying on the graphql-java and graphql-spring-boot within a spring-boot application, we will dissect the underlying mechanism of errors handling within these libraries to let you know what are your possibilities when it comes to customizing some of the default error handling mechanisms.

Application Set up

We will use a simple spring-boot sample-graphql-error-handling that will expose two endpoints:

createUser(username:string, password:string) that fails if a user is already registered with the same username.

getUser(username:string,password:string) that fails if no user is existing for the given username.

Generate the project using Spring Initializr and add the following dependencies to the pom.xml file:

Minimal maven dependencies to enable graphql implementation within a spring boot app

Our User model Class: User.java

The User model class

The Schema definition file: src/main/resources/UserQL.graphqls

User.graphqls

The schema speaks for itself, we will have a read request getUser which will return a User corresponding to the username and password given as parameters, and a write request which will register a User with its credentials as parameters.

We will use a service class, acting as our business logic that will maintain a list of in-memory users. This service will be injected into our resolvers later.

UserService.java

The createUser method will return a UserAlreadyExistsException if a user already exists.

Similarly, the getUsermethod will return a UserNotFoundException in case no user is found.

Next, we have the code of our exceptions:

UserAlreadyExistsException.java

UserNotFoundException.java

We will rely on these customized exceptions to return relevant information to the customer.

Finally, the resolvers code:

UserQuery.java

UserMutation.java

Now that the project is set up, we can start sending the requests and analyze the errors.

Run the spring boot app and launch the graphiql tool within the browser with: http://localhost:8080/graphiql if you are running on the local machine with the default spring boot app port.

The generic error (case#1)

Within the graphiql tool, let's start by creating a user:

mutation {
  createUser(username: "johndoe", password: "pwd") {
    id
  }
}

Everything is OK and the user is indeed created as confirmed by the answer:

If we try to get a non-existing user:

mutation {
  createUser(username: "johndoe", password: "def") {
    id
  }
}

Not only are the details as defined by the specification missing, but the error message is also inconsistent, as it indicates a server-side error yet it is a client-side error.

Also, if we try to create a user that is already existing:

mutation {
  createUser(username: "johndoe", password: "pwd") {
    id
  }
}

Let’s consider what just happened as CASE #1

For CASE #2 : We need to customize the information according to the error that occurred while giving the client additional information about what happened in the backend so that he can react accordingly.

Customizing errors (case#2)

We've already taken a step forward by defining and throwing problem-related customized exceptions. However, these exceptions need to be transformed into GraphQL errors that respect the standard format before being sent to the client.

graphql-java provides the GraphQLError interface representing a GraphQL standard error that our exceptions will implement.

Our exceptions become:

UserAlreadyExistsException.java as GraphQLError

UserNotFoundException.java as GraphQLError with extra data

Overriding getLocations() and getErrorType() is mandatory.

We will just return nullin these methods because they are ignored by the default error handler anyway.
We will see why later.

In the case of wrong identification data, we want to add an “invalidField” field under the key “extensions” of the error to indicate to the customer which field is in error and needs to be corrected.

This is why we redefine the getExtensions() method in UserNotFoundException

Don’t forget to change the instantiation of the exception in UserService.java.

throw new UserNotFoundException(“We were unable to find a user with the provided credentials”, “username”);

Let’s start the application again and run the same test scenario with graphiql to compare the results.

Let’s start by creating a user, the answer is, unsurprisingly, this one:

Then, if you try to retrieve a user that doesn’t exist, the request results in the following error:

Note the invalid field present in the extensions block of the result.

Also, If we try to create a user with an existing username, the response is as follows:

Let’s dissect what just happened in both cases #1 and #2:

When we throw an exception while fetching data:

1. The exception is handled by default by the `SimpleDataFetcherExceptionHandler`

The handler wraps 4 things: the thrown custom exception (the RuntimeException), the exception message, the error locations, and the extensions, within an ExceptionWhileDataFetchingerror (which is an implementation of the GraphQLErrorinterface).
Then, the ExceptionWhileDataFetching is added to the list of errors of the query result. As we can see in the following SimpleDataFetcherExceptionHandler code.

SimpleDataFetcherExceptionHandler.java

At line 10, a new ExceptionWhileDataFetching is constructed with the error path, our exception, and the sourceLocation.

Remember I told you the methods getLocations() and getErrorType() of our exception were ignored?
Well here’s why:

ExceptionWhileDataFetching.java

In this code snippet from the ExceptionWhileDataFetching class, only the methods getMessage() and getExtensions() are called, the path and the sourceLocation are already provided upon class instantiation.

2. The DefaultGraphQLErrorHandler

After the SimpleDataFetcherExceptionHandler process, another handler, defined by the graphql-spring-boot library comes into action to handle the returned list of errors.
He is the GraphQLErrorHandler: the default implementation is the DefaultGraphQLErrorHandler

These 2 steps can be illustrated as follows:

The Simple DataFetcherExceptionHandler process

The DefaultGraphQLErrorHandler process

In case#1: Our custom exceptions were not instances of GraphQLErrors, the DefaultGraphQLErrorHandler considered them as internal server errors, containing details that should not reach the client. They were filtered and converted to GenericGraphQLError as illustrated.

In case#2: Our custom exceptions were instances of GraphQLErrors, hence they were not reduced to Generic graphQL errors.

This behavior is described in the DefaultGraphQLErrorHandler::processErrors() method.

DefaultGraphQLErrorHandler::processErrors()

Now we clearly understand why we get such a useful error response and a valid format for case#2.

If the SimpleDataFetcherExceptionHandler behavior doesn’t fit your use case, you can create a CustomDataFetcherExceptionHandlerimplementing DataFectcherExceptionHandler, then define your own logic and throw something different than an ExceptionWhileDataFetching GraphQLError.

However, this is not something I will advise as you can find yourself breaking the rules of the GraphQL Specification by sending non-standard error messages. Unless you really understand what you are trying to implement.

Besides, customizing this behavior implies modifying the query execution strategy. As graphql-spring-boot integration is relying on graphql-java to implement the query execution strategy, you will have to deal with them, which, IMHO, does not worth it, as they already implement a pretty good behavior.

Similarly, If the DefaultGraphQLErrorHandlerbehavior doesn’t fit your use case, you can create a CustomGraphQLErrorHandler implementing GraphQLErrorHandler, then define your own logic and handle GraphQLErrors differently.

Let’s supposed we are not satisfied by the string: Exception while fetching data (/xxxx) which is automatically appended to the error message sent to the user, and we just want our original message in the error, without any fancies. We will send our unwrapped original custom exception to the final user by defining a CustomGraphQLErrorHandler.

Sending unwrapped exception

We create the CustomGraphErrorHandler as follows:

CustomGraphQLErrorHandler.java

We override the processErrors method by telling the handler to: first check if the exception is an ExceptionWhileDataFetching then extract our original exception( UserNotFoundException, UserExistsException …) and return it. Otherwise, the handler will just return the received exception as it is.

If we try to find a non-existing user, we get the following error:

As our exceptions are sent back to the user unwrapped, the message is now concise and precise.

Conclusion

In this article, we were focusing two notions:

Setting up your Spring-boot project to host your first GraphQL API entry points,

Understanding how the graphql-java implementation and graphql-spring-boot handle errors triggered within an application.

We have covered the following sections:

Setting up a sample project
Understanding the standard Graphql error response format
Diving into the mechanisms behind generic graphql errors and more tailored ones
Adding additional custom information to the error
Getting to know the possibilities of further error customizations.

The Github repo about this article is available here.

In the next article, we will see how to Secure our APIs with pretty simple steps.

Thanks for reading, feedback is a gift 🎁.

GraphQL, from Theory to Real-world with Spring-boot

imphilippesimo — Sat, 13 Jun 2020 16:46:28 +0000

This article is the first part of a series of articles that we will go through. The series is about mastering the necessary core concepts of the GraphQL Specification to set up a real-world server-side implementation example with spring boot. Each episode is designed to be consumed independently so feel free to start from what interests you the most.

GraphQL Core concepts (this one) 📈
Getting started with the core concepts of GraphQL to build a real-world example
First GraphQL API and Efficient graphQL error handling in Spring-boot 🧯
Secure your graphQL APIs within a Spring-boot ‍👮‍♂️
Set up access control level on your APIs to define who can have access to which if your APIs
Testing your graphQL APIs in a Spring-boot app 🚀
Writing unit and integration tests for your graphQL APIs
Set up your Spring-boot project and expose your firsts GraphQL endpoints Get an in-depth understanding of GraphQL error handling mechanisms.

Overview

What is GraphQL?

It is a new API Standard developed and used by Facebook since 2012 but open-sourced since 2015. It is a more flexible and powerful alternative to REST.
GraphQL specification has a rapidly growing community and some of the popular companies that use that are Github, Coursera, Twitter, Shopify, yelp, to name only a few.

GraphQL vs REST

The idea behind REST is great as it advocates the usage of stateless servers and structured access to resources. But there are shortcomings such as inefficiencies and lack of flexibility encountered by developers and that's why graphQL was developed for.
To better illustrate the differences, we will introduce the Social Shopping App (SSApp) that we are going to develop all along with this series.
SSApp:
Our app consists of users, browsing some shopping articles within the app that they can like and buy. Users can sell articles and follow other users so that they can check their activities on the app. That's it!
Ok, let's come back to the illustration, consider we want to display the user home screen:

To achieve this is REST:
We need, 3 API endpoints from the server:
/users/<id>
Returning:

{
  "user": {
    "id": "flkzopgz12"
    "name": "Samanta Calgon"
    "address": {...}
    "birthday": "May 15, 1995"
  }
}

Notice we just need the name, but we are fetching useless additional data at this point. We are draining the user data plan. 🤦‍♂️
Then:

/users/<id>/articles?liked=true
Returning:

{
  "articles": [{
    "id": "dmflgmjlsfgs4z545"
    "title": "Vuicci Sweet Shirt",
    "description": "Lorem ipsum ...",
    "liked": "true"
    "reviews": [...]
  },{
    "id": "dlkfjge919zzz"
    "title": "Diara Eau de Parfum",
    "description": "dolor epsumet ...",
    "liked": "true"
    "reviews": [...]
  },{...}
  ...
  ]
}

This time also, we just need the title of the articles.
And
/users/<id>/followers
Returning:

{
  "followers": [{
      "id" : "dlkfhosdid2e15",
      "name" : "Klark",
      "address": { ... },
      "birthday": "January 21, 1998"
    },{
      "id" : "94erg48h4j",
      "name" : "Rose",
      "address": { ... },
      "birthday": "January 21, 1998"
    },{ ... }    
    ... 
  ]
}

Here, we are downloading a lot of data that we don't need as well.🤦‍♂️

The fact that we are getting more than the data than we essentially want is called over fetching.

The fact that we can't get enough information in one request, and need to send many ones to gather all information is known as the under fetching problem.

Yes, you can adapt your REST API to the screen so that it returns only the data needed for display, using the so-called View Models.

By doing this, you are highly coupling your views to the endpoints. This way, each time the view will evolve, your API shall evolve too. Which is very bad for API scalability.

Fortunately, we can solve the above problems with graphQL. 🔥

We can retrieve what we need by issuing only one request. GraphQL uses only one endpoint, usually /graphql.

Sending a request in GrapQL means issuing a post request at this endpoint, and describe in the request body what data do we exactly need from the server.

query {
  User(id: "flkzopgz12") {
    name
    articles(liked: True) {
      title
    }
    followers{
      name
    }
  }
}

Notice how we tell the server exactly what we need with expressions corresponding to the data model schema:

User.name, User->articles.title, User->followers.name .

The server will then process and match this description to the corresponding methods to get the data.

Those methods are known as the resolvers.

Resolvers will get the data from a DB, another web service, etc then package them into a JSON object and return them to the client.

{
  "data": {
    "user": {      
      "name": "Samanta Calgon", 
      "articles": [
        { "title": "Vuicci Sweet Shirt"}
        { "title": "Diara Eau de Parfum"}
        { "title": "Timiland Shoes"}
        { "title": "Lavis Jeans White Vintage"}
      ],
      "followers": [
        { name: "Klark"},
        { name: "Rose"},
        { name: "Rick"},
        { name: "Josh"},
      ]
    }
  }
}

The root field of the data part of a graphQL response is data , according to the graphQL specification.

GraphQL vs REST in a nutshell

No more over and under fetching,
No need to adapt the APIs to the view which enables rapid product iterations.

Moreover, GraphQL uses a strong type system to define the cans and cants of your API.
You just have to define your types in a Schema file, written in the Schema Definition Language (SDL).
This schema will represent the contract between the Frontend and the backend teams, enabling them to work independently in an API-first like fashion.
Now that you know why GraphQL is a better alternative to REST, we can now dive into the core concepts of GraphQL.

GraphQL Core Concepts

The Schema Definition Language (SDL)

It lets us define our schema, which is made up of types.
This example illustrates a one-to-many relationship between 2 types:

type User {
  id: ID!                  # Value generated by the server
  name: String!            # String,Int,ID are built-in type
  age: Int!                # ! means age is required
  articles: [Article!]     # A user can be have many Articles
}
type Article {
  title: String!
  seller: User!            # An article is sold by a User
  description: String
}

In GraphQL, fetched data are not fixed, as you saw earlier, you can decide to retrieve ONLY the User articles, or retrieve JUST the User age, or even JUST the Users articles' title. The client decides of what he needs

One important thing to notice is that, because we didn't define a field password in the User type in the schema, this field is unretrievable by the client. No more need to bother with JsonIgnore configurations. That's the power of the GraphQL strong type system. The server decides of what is possible or not for the client

The client decides of what he needs.

The server decides of what is possible or not for the client.

The client decides what he needs by sending requests to the server
These are the three kind of requests:

Query: Retrieve data
Mutation: Change data
Subscription: Event-based real-time notifications

Examples:

# Query
query{            #starts with the keyword query
  allUsers {
    name
  }
}
# returns
{
  "allUsers" : [
    {"name":"Samanta Calgon"},
    {"name":"Carlos Chavez"},
    ...
  ]
}
# Mutation
mutation{        #starts with the keyword mutation
  createUser(name: "Miguel Reyes", age: "21") {
    id
  }
}
# returns
{
  "createUser" : {
    "id" : "slkdjfr96f4d"
  }
}
# Subscription, listening to new articles creation
susbscription {    #starts with the keyword susbscription      
  newArticle {
    title
    description
    seller {
      name
    }  
  }
}
#When an article is created by another client, 
#while the subscription is active, this client will receives
{
  "Article" : {
    "title" : "Marins Jacket, green",
    "description" : "Real Marins Jacket refurbished from 2015"
    "seller" : {
      "name":"Carlos Chavez"
    }
  }
}

__The Server decides what is possible or not by defining the schema__

The schema, as mentioned earlier, is the contract between client and server, is written using SDL and defines the capabilities of the API by the means of GraphQL types.

Functionally, we can see types as of 2 kinds:

Types to describe the data structure, custom, and built-in ones (User, Article, String, ID, …)
Types to describe the entry points exposed by the API (Query, Mutation, and Subscription)


#Custom and buitl-in Data Structure types
type User {
  id: ID!                  # Value generated by the server
  name: String!            # String,Int,ID are built-in type
  age: Int!                # ! means the field is required
  articles: [Article!]     # A user can be have many Articles
  followers: [User]
}
type Article {
  title: String!
  seller: User!            # An article is sold by a User
  description: String
}


#Types describing entrypoints
type Query {
  allUsers(last: Int): [User!]! #last parameter is optional
  user(id: Int): User       #No '!', The returned user can be empty
  #...
}
type Mutation {
  createUser(name: String, age: Int): User!
  #Want the client to create an article ? define the operation here
  #...
}
type Subscription {
  newArticle: Article! 
}

Now that you have a better vision of what is GraphQL, you are able to step through the next part which is about writing your first GraphQL API with Spring Boot.

Conclusion

GraphQL is a better alternative to REST because it offers flexibility and efficiency during application development. This article aimed to prove that while explaining the core concepts of this specification.

Nevertheless, GraphQL is just a specification, that needs to be implemented for both the client and server-side. We will focus on the server-side, especially with Java and Spring-boot for the next parts of this series.

Feedback is a Gift 🎁!

DEV Community: imphilippesimo

Testing your GraphQL APIs in a Spring-boot app

Secure your GraphQL API within a Spring-Boot App

Overview

TL;DR

Project Setup

Securing the resources

Conclusion

Understanding GraphQL Error Handling mechanisms in Spring-boot

Overview

TL;DR

GraphQL quick summary

With great power comes great responsibilities

Application Set up

The generic error (case#1)

Customizing errors (case#2)

1. The exception is handled by default by the SimpleDataFetcherExceptionHandler

2. The DefaultGraphQLErrorHandler

Sending unwrapped exception

Conclusion

GraphQL, from Theory to Real-world with Spring-boot

Overview

What is GraphQL?

GraphQL vs REST

GraphQL Core Concepts

The Schema Definition Language (SDL)

The client decides of what he needs.

The server decides of what is possible or not for the client.

Conclusion

1. The exception is handled by default by the `SimpleDataFetcherExceptionHandler`