GraphQL now and thank me later!

What is GraphQL about?

Key Differences

See it in <code>

1. Get list of users

2. Get one specific user detail

3. Create new user

@RestController
@RequestMapping("/users")
public class UserController {

    private UserRepository userRepository;

    public UserController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @GetMapping
    public List<User> getUsers() {
        return userRepository.findAll();
    }

    @GetMapping("/{id}")
    public User getUserById(@PathVariable Long id) {
        return userRepository.findById(id).orElse(null);
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userRepository.save(user);
    }
}

@Configuration
public class GraphQLConfiguration {

  private UserRepository userRepository;

  public GraphQLConfiguration(UserRepository userRepository) {
      this.userRepository = userRepository;
  }

  @Bean
  public GraphQL graphQL() {
      GraphQLObjectType queryType = GraphQLObjectType.newObject()
              .name("query")
              .field(GraphQLFieldDefinition.newFieldDefinition()
                      .name("users")
                      .type(new GraphQLList(userType()))
                      .dataFetcher(environment -> userRepository.findAll())
                      .build())
              .field(GraphQLFieldDefinition.newFieldDefinition()
                      .name("user")
                      .type(userType())
                      .argument(GraphQLArgument.newArgument()
                              .name("id")
                              .type(Scalars.GraphQLID)
                              .build())
                      .dataFetcher(environment -> {
                          String id = environment.getArgument("id");
                          return userRepository.findById(Long.valueOf(id)).orElse(null);
                      })
                      .build())
              .build();

      GraphQLObjectType mutationType = GraphQLObjectType.newObject()
              .name("mutation")
              .field(GraphQLFieldDefinition.newFieldDefinition()
                      .name("createUser")
                      .type(userType())
                      .argument(GraphQLArgument.newArgument()
                              .name("user")
                              .type(userInputType())
                              .build())
                      .dataFetcher(environment -> {
                          UserInput userInput = environment.getArgument("user");
                          User user = new User();
                          user.setName(userInput.getName());
                          user.setEmail(userInput.getEmail());
                          return userRepository.save(user
                        );
                      })
                      .build())
              .build();
              
      GraphQLSchema schema = GraphQLSchema.newSchema()
              .query(queryType)
              .mutation(mutationType)
              .build();

    return GraphQL.newGraphQL(schema).build();
  }

  private GraphQLObjectType userType() {
      return GraphQLObjectType.newObject()
              .name("User")
              .field(GraphQLFieldDefinition.newFieldDefinition()
                      .name("id")
                      .type(Scalars.GraphQLID)
                      .build())
              .field(GraphQLFieldDefinition.newFieldDefinition()
                      .name("name")
                      .type(Scalars.GraphQLString)
                      .build())
              .field(GraphQLFieldDefinition.newFieldDefinition()
                      .name("email")
                      .type(Scalars.GraphQLString)
                      .build())
              .build();
  }
  
  private GraphQLInputObjectType userInputType() {
      return GraphQLInputObjectType.newInputObject()
              .name("UserInput")
              .field(GraphQLInputObjectField.newInputObjectField()
                      .name("name")
                      .type(Scalars.GraphQLString)
                      .build())
              .field(GraphQLInputObjectField.newInputObjectField()
                      .name("email")
                      .type(Scalars.GraphQLString)
                      .build())
              .build();
  }
}

@RestController
@RequestMapping("/graphql")
public class GraphQLController {
  private GraphQL graphQL;

  public GraphQLController(GraphQL graphQL) {
      this.graphQL = graphQL;
  }
  
  @PostMapping
  public Map<String, Object> executeQuery(@RequestBody Map<String, String> request) {
      ExecutionResult result = graphQL.execute(ExecutionInput.newExecutionInput()
              .query(request.get("query"))
              .operationName(request.get("operationName"))
              .variables(request.get("variables"))
              .build());
      return result.toSpecification();
  }
}

public class ApiClient {
  private RestTemplate restTemplate = new RestTemplate();

  public List<User> getUsersFromREST() {
      return restTemplate.getForObject("http://localhost:8080/users", List.class);
  }
  
  public User getUserByIdFromREST(long id) {
      return restTemplate.getForObject("http://localhost:8080/users/" + id, User.class);
  }
  
  public User createUserWithREST(User user) {
      return restTemplate.postForObject("http://localhost:8080/users", user, User.class);
  }
  
  public Map<String, Object> executeQueryWithGraphQL(String query) {
      HttpHeaders headers = new HttpHeaders();
      headers.setContentType(MediaType.APPLICATION_JSON);
  
      HttpEntity<String> requestEntity = new HttpEntity<>(
              "{\"query\": \"" + query + "\"}",
              headers
      );
  
      ResponseEntity<Map> responseEntity = restTemplate.exchange(
              "http://localhost:8080/graphql",
              HttpMethod.POST,
              requestEntity,
              Map.class
      );
  
      return responseEntity.getBody();
  }
}

@Test
public void testGetUsers() {
  ApiClient apiClient = new ApiClient();
  // Test REST API
  List<User> usersFromREST = apiClient.getUsersFromREST();
  assertEquals(3, usersFromREST.size());
  assertEquals("Alice", usersFromREST.get(0).getName());
  assertEquals("Bob", usersFromREST.get(1).getName());
  assertEquals("Charlie", usersFromREST.get(2).getName());
  
  // Test GraphQL API
  Map<String, Object> resultFromGraphQL = apiClient.executeQueryWithGraphQL("{ users { name } }");
  List<Map<String, String>> usersFromGraphQL = (List<Map<String, String>>) resultFromGraphQL.get("data");
  assertEquals(3, usersFromGraphQL.size());
  assertEquals("Alice", usersFromGraphQL.get(0).get("name"));
  assertEquals("Bob", usersFromGraphQL.get(1).get("name"));
  assertEquals("Charlie", usersFromGraphQL.get(2).get("name"));
}

Nice! Let's migrate

There is no universal best API style. There is always a best API style for your problem. Don't choose a technology and fit a problem to it. Let's take a look of the characteristics of your system and work backwards.

When to use

• When the client needs a flexible and efficient way to request specific data: Because the client can specify exactly what data it needs with GraphQL, it can be a more flexible and efficient way to request data from the server. This can be particularly useful for mobile applications, where network bandwidth is limited and the client may not need all of the data that is provided by the server.

• When the API needs to support multiple clients with different data requirements: With GraphQL, each client can request the specific data that it needs, rather than getting a fixed set of data from the server. This can be useful when the API needs to support multiple clients with different data requirements, as it allows each client to get only the data that it needs.

• When the API needs to be self-documented: GraphQL includes a built-in documentation system, as the client can request the schema of the API to see the types of data that are available and the fields that can be queried. This can make it easier for developers to understand and use the API, as they don't have to refer to separate documentation or make trial-and-error requests to figure out what data is available.

Takeaways & what's next

References

Learn GraphQL Fundamentals with Fullstack Tutorial

Learn all about GraphQL and why it is an API technology that's superior to REST. It is not only for React & Javascript developers but can be used for any API.

https://www.howtographql.com/basics/0-introduction/

What is a REST API?

A REST API (also known as RESTful API) is an application programming interface that conforms to the constraints of REST architecture. REST stands for representational state transfer.

https://www.redhat.com/en/topics/api/what-is-a-rest-api

Fielding Dissertation: CHAPTER 5: Representational State Transfer (REST)

This chapter introduces and elaborates the Representational State Transfer (REST) architectural style for distributed hypermedia systems, describing the software engineering principles guiding REST and the interaction constraints chosen to retain those principles, while contrasting them to the constraints of other architectural styles. REST is a hybrid style derived from several of the network-based architectural styles described in Chapter 3 and combined with additional constraints that define a uniform connector interface. The software architecture framework of Chapter 1 is used to define the architectural elements of REST and examine sample process, connector, and data views of prototypical architectures.

https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

REST vs GraphQL APIs, the Good, the Bad, the Ugly

GraphQL adoption is exploding, but should you migrate to GraphQL?

https://www.moesif.com/blog/technical/graphql/REST-vs-GraphQL-APIs-the-good-the-bad-the-ugly/

GraphQL vs REST - A comparison

Learn why GraphQL is a more efficient and flexible alternative to REST APIs. It has a strong type system and avoids frontend issues like over- and underfetching.

https://www.howtographql.com/basics/1-graphql-is-the-better-rest/