REST vs GraphQL: Comparing and Contrasting Two API Architectures

When building applications that rely on external data, one of the most critical decisions developers face is choosing the right API architecture. Representational State Transfer (REST) and GraphQL are two of the most prominent architectures used to expose and consume APIs, each offering unique advantages and challenges.

In this blog, we will delve into a comprehensive analysis of REST vs. GraphQL. By the end of this in-depth article, you’ll gain a full understanding of both technologies, their principles, strengths, weaknesses, and when to choose one over the other. The comparison will cover various technical, performance, scalability, security, and usability aspects.

1. What is REST?

Overview

REST (Representational State Transfer) was first introduced by Roy Fielding in his 2000 doctoral dissertation as a set of architectural principles for designing distributed systems. At its core, REST is an architectural style, not a protocol. It leverages HTTP protocols for communication between clients and servers, and it focuses on making web services easier to understand and scale. Since then, REST has become the most common approach for building APIs (Application Programming Interfaces) and is widely used by large companies like Facebook, Twitter, and GitHub..

Key Concepts and Principles

REST is built upon a set of constraints and principles that guide the interaction between clients and servers. Understanding these principles is essential for grasping how REST APIs function.

Statelessness: In a RESTful API, every client request to the server must contain all the information needed to process it. This means that the server does not store any client context between requests, which allows for greater scalability.
Client-Server Architecture: REST promotes the separation of concerns between the client (which interacts with the user interface) and the server (which handles data storage and business logic). This ensures a more modular system where changes to one do not affect the other.
Uniform Interface: A key aspect of REST is its standardized interface for interacting with resources. HTTP methods (GET, POST, PUT, DELETE, PATCH) are used to interact with resources, and the same URLs and patterns are used across different clients.
Resource-Based: REST organizes data as “resources,” which are identified by URLs (Uniform Resource Locators). Each resource is manipulated via HTTP methods, and the server responds with data in formats such as JSON or XML.
Stateless Communication: Since REST adheres to statelessness, each HTTP request is considered independent and contains all the necessary information to complete the action. This allows RESTful services to scale horizontally, as requests can be handled by any server without requiring previous state knowledge.
Cacheability: REST APIs can declare resources as cacheable or non-cacheable to enhance performance. Clients can store copies of responses to avoid making repeated calls to the server, reducing latency and server load.
Layered System: REST supports a layered system where the architecture is composed of hierarchical layers. These layers can be implemented independently without affecting each other, which provides flexibility and scalability.
Code on Demand (Optional): REST can allow servers to extend functionality by sending executable code (such as JavaScript) to the client. However, this is an optional constraint and is not commonly used in most implementations.

HTTP Methods and Status Codes

RESTful APIs typically make use of HTTP methods to perform CRUD (Create, Read, Update, Delete) operations on resources. Here’s how these map to RESTful concepts:

GET: Retrieve a resource or a collection of resources.
POST: Create a new resource.
PUT: Update an existing resource.
PATCH: Partially update a resource.
DELETE: Remove a resource.

HTTP status codes are used to inform clients about the outcome of their requests. Common status codes include:

200 OK: The request was successful.
201 Created: A new resource has been created.
400 Bad Request: The request was malformed or invalid.
404 Not Found: The requested resource does not exist.
500 Internal Server Error: A server-side issue occurred.

RESTful Design Patterns

REST design typically involves organizing resources hierarchically using URIs. For example, in an e-commerce application:

GET /products would return a list of products.
GET /products/123 would return the product with ID 123.
POST /products would create a new product.

REST encourages logical grouping of resources with meaningful, predictable URLs, making the API more intuitive to use.

2. What is GraphQL?

Overview

GraphQL is a query language for APIs and a runtime for executing those queries against your data. Developed by Facebook in 2012 and released as open-source in 2015, GraphQL was designed to provide a more efficient, flexible, and powerful alternative to REST, especially when dealing with complex, nested data structures.

GraphQL is centered around providing clients with more control over the data they receive. It introduces a new way of querying APIs, where clients define the shape and structure of the data they need, and the server responds accordingly. Let’s break down its core principles:

Single Endpoint: Unlike REST, which has multiple endpoints for different resources, GraphQL uses a single endpoint for all interactions. This single entry point serves both queries (for reading data) and mutations (for writing or updating data).
Schema and Type System: One of GraphQL’s defining features is its strong, type-safe schema. The schema defines the structure of the data, specifying what queries can be made and what data types will be returned. The schema ensures that clients can only request valid data.
Declarative Data Fetching: In GraphQL, clients specify the exact shape of the data they want in their queries. This prevents over-fetching or under-fetching, which are common issues in REST. If a client only needs the name and age of a user, for example, it can request just those fields, rather than receiving the entire user object.
Nested Queries: GraphQL allows for nested queries, where you can fetch related data in a single request. For example, you could request information about a user and also retrieve the posts they have authored in the same query. This reduces the need for multiple round trips to the server.
Mutations: In addition to queries (which are read-only), GraphQL also provides mutations for creating, updating, or deleting data on the server. Like queries, mutations are executed in a type-safe way and return the data that was affected.
Real-Time Capabilities (Subscriptions): GraphQL offers a mechanism for real-time updates through subscriptions. Subscriptions allow clients to listen for changes on the server and automatically receive updates when specific events occur. This is commonly used in scenarios like chat applications, live feeds, or dashboards.
Version-Free: Unlike REST, which often involves versioning (e.g., /v1/users vs. /v2/users), GraphQL is inherently versionless. As long as new fields are added to the schema in a backward-compatible way, clients can request only the fields they need without worrying about API versions.
Strongly Typed: GraphQL enforces a strict type system through its schema, which defines the types of data (such as scalars like strings, integers, and custom types like users or posts). This makes it easier to catch errors and ensure data consistency between the client and server.

GraphQL allows clients to specify exactly the data they need, making data retrieval more efficient. It also introduces a type system to define the API structure, enabling powerful introspection and validation features.

Key Concepts and Principles

Query Language: Clients write queries in GraphQL, specifying the exact data they need, often in a single request. This contrasts with REST, where multiple endpoints may need to be accessed for different resources.
Strong Typing: GraphQL APIs are strongly typed, meaning every field in the schema has a specific type (e.g., String, Int, Boolean). This makes GraphQL APIs self-documenting, as the schema itself serves as the contract between the client and server.
Single Endpoint: Unlike REST, where multiple endpoints represent various resources, GraphQL uses a single endpoint. Queries are sent to this endpoint, and the server interprets and responds with the required data.
Mutations: In addition to queries (used for reading data), GraphQL introduces mutations for creating, updating, or deleting data.
Resolvers: GraphQL queries are executed via resolvers, which fetch the appropriate data. This decouples data fetching from the API, allowing different backends or databases to provide data seamlessly.

Query Language and Structure

GraphQL queries are JSON-like, where the client specifies the structure of the desired response. For instance, if you want to retrieve a user’s name and the titles of their recent posts, you might write a query like this:

JSON

{
  user(id: 1) {
    name
    posts {
      title
    }
  }
}

The response matches the structure of the query:

JSON

{
  "data": {
    "user": {
      "name": "John Doe",
      "posts": [
        { "title": "GraphQL vs REST" },
        { "title": "Building APIs" }
      ]
    }
  }
}

Schema and Type System

GraphQL’s schema is a core part of the API. The schema defines types, queries, mutations, and their relationships. Here’s an example of a simple GraphQL schema:

graphqlCopy codetype User {
  id: ID!
  name: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String
}

type Query {
  user(id: ID!): User
  posts: [Post!]!
}

This schema defines two types, User and Post, and two queries: one to get a user by ID and one to retrieve all posts.

3. Comparing REST and GraphQL

3.1 Architecture

REST Architecture: REST is based on a client-server architecture that focuses on resources, where each resource has its own URL. Clients interact with resources via HTTP methods (GET, POST, PUT, DELETE), and the server responds with a representation of the resource in a standardized format (e.g., JSON). The stateless nature of REST simplifies scaling because each request is independent and doesn’t require server-side state management.
GraphQL Architecture: GraphQL follows a more flexible, schema-driven approach. Rather than relying on multiple URLs for different resources, GraphQL operates via a single endpoint. Clients send queries that define precisely what data they need, and the server responds with exactly that data. This approach allows for a more granular, client-driven experience but introduces some complexity on the server side as it needs to parse and process dynamic queries.

Comparison: REST’s resource-based architecture works well for applications with a clear and stable set of resources, while GraphQL’s flexible schema and single endpoint offer more versatility for dynamic data fetching scenarios.

3.2 Data Fetching Mechanisms

REST: In REST, clients request resources, and the server responds with a complete representation of those resources. If a client needs user data, it may have to fetch the entire user object, even if only a subset of the fields is required. Similarly, if related data is needed (e.g., posts authored by the user), it might require multiple requests to different endpoints.
GraphQL: In GraphQL, clients specify the exact data they need in a single query. This reduces both over-fetching and under-fetching of data. For example, a client can request just the name and email of a user, and GraphQL will return only those fields. Nested data can also be requested in the same query, reducing the need for multiple network requests.

Comparison: GraphQL excels in scenarios where clients need to request varying subsets of data. In contrast, REST’s predefined data structures can lead to over-fetching or under-fetching, but REST might perform better for simple, fixed data requirements.3.3 Flexibility

REST: REST APIs are often more rigid because they follow a resource-based structure. Each resource has its own endpoint, and the server defines what data is returned. If new fields are added to a resource or if the structure changes, new endpoints may be required, or modifications to existing endpoints may be necessary. This rigidity can make it more difficult to adapt REST APIs to changing client needs without versioning the API.
GraphQL: GraphQL is highly flexible and client-driven. Clients define the exact shape and structure of the data they want to receive by writing custom queries. The server exposes a schema, and clients can request any combination of fields or nested data in a single query. This flexibility allows GraphQL to adapt to changing requirements without needing to create new endpoints or version the API. As a result, GraphQL is often preferred for complex applications with dynamic data needs or when multiple clients with different data requirements are involved (e.g., mobile apps vs. web apps).

Comparison: GraphQL’s flexibility provides greater control to the client and allows for more efficient data fetching. REST, on the other hand, offers less flexibility due to its resource-based structure, but this simplicity can be advantageous for certain use cases where flexibility is not a major concern.

3.4 Performance

REST: One of the major performance issues with REST is over-fetching and under-fetching of data. Since REST endpoints often return a full resource representation, clients may receive more data than necessary (over-fetching). On the other hand, if related resources are required, clients may need to make multiple requests to different endpoints to gather all the data they need (under-fetching). These additional requests can result in increased network overhead and latency.Another factor is REST’s reliance on HTTP methods like GET, POST, PUT, and DELETE, which are inherently stateless. While this statelessness enables scalability, it doesn’t inherently optimize for reduced round trips to the server.
GraphQL: GraphQL is designed to minimize both over-fetching and under-fetching. Since clients can request only the fields they need and nest related resources in a single query, there is less need for multiple round trips to the server. This can significantly reduce network overhead, especially in complex applications with deeply nested data.However, GraphQL’s flexibility can also lead to performance challenges on the server side. Handling complex queries and resolving nested fields can increase the server’s workload, particularly if queries are poorly optimized or if clients request large amounts of deeply nested data. This can be mitigated by server-side optimizations, query complexity analysis, and the use of tools like DataLoader for batching and caching requests.

Comparison: GraphQL generally reduces client-side performance issues by minimizing over-fetching and under-fetching, but it can introduce server-side complexity. REST is more predictable in performance but can lead to inefficiencies in terms of the number of requests and the amount of data transferred.

3.5 Error Handling

REST: In REST, error handling is typically handled through standard HTTP status codes. For example:
- 200 OK: Successful response
- 404 Not Found: Resource not found
- 500 Internal Server Error: Server-side error
REST APIs provide a clear and standardized way of communicating errors via HTTP response codes, and additional error details can be provided in the response body.
GraphQL: GraphQL has its own mechanism for handling errors. A successful GraphQL request always returns a 200 HTTP status code, even if there are errors in the query. Instead of relying on HTTP status codes, errors are returned in the response body under an errors key. These errors can be related to syntax issues, validation errors, or server-side problems.This approach allows GraphQL to return partial results along with error information. For example, if part of a query succeeds and part fails, GraphQL will return the successful data along with details of the failure. While this can be useful, it also complicates error handling, as clients need to parse the error object to handle failures properly.

Comparison: REST’s error handling is more straightforward due to its use of standardized HTTP status codes. GraphQL offers more granular error handling but requires a more complex client-side error management process.

3.6 Caching

REST: REST APIs leverage HTTP caching mechanisms like ETag, Last-Modified, and Cache-Control headers. These are powerful tools that allow clients and intermediate proxies to cache responses efficiently. For example, an API can set caching policies for resources that don’t change often, reducing the number of requests to the server and improving client-side performance.
GraphQL: Caching in GraphQL is more complex because a single query can request multiple resources with varying lifetimes and caching requirements. Since there’s only one endpoint, it doesn’t inherently benefit from HTTP caching in the same way REST does. Caching needs to be handled at the field level, and this can be done using client-side tools like Apollo Client or Relay, which provide mechanisms to cache query results.Server-side caching in GraphQL can also be implemented using tools like DataLoader, which batch and cache database or API calls. However, the complexity of GraphQL’s queries (particularly nested queries) makes caching more challenging compared to REST’s simpler, resource-based architecture.

Comparison: REST benefits from built-in HTTP caching mechanisms, making it more cache-friendly. GraphQL requires more effort and custom implementations to achieve effective caching, although modern libraries are making this easier.

3.7 Security

REST: REST APIs typically rely on well-established security mechanisms such as OAuth 2.0, API keys, JWT (JSON Web Tokens), and HTTPS for encryption. These techniques can be used to secure individual endpoints and protect sensitive data.One common security concern in REST is over-fetching, which may expose unnecessary data if the API response includes more information than the client actually needs. This can be mitigated by designing more specific endpoints or filtering data on the server side.
GraphQL: GraphQL uses similar security mechanisms as REST (e.g., OAuth 2.0, API keys, JWT, HTTPS). However, because GraphQL allows clients to specify the exact data they want, there is a risk of introspective queries or malicious clients requesting large amounts of data or complex queries that could lead to denial-of-service (DoS) attacks.To address these concerns, GraphQL APIs often implement rate-limiting, query complexity analysis, and query whitelisting to prevent abuse. Moreover, developers can control what data is exposed in the schema, limiting the risk of clients accessing unauthorized fields or relationships.

Comparison: Both REST and GraphQL rely on the same core security principles (authentication, authorization, encryption). However, GraphQL’s flexibility introduces additional risks (e.g., complex or introspective queries), requiring more sophisticated server-side protections.

3.8 Versioning

REST: Versioning is a common practice in REST APIs to introduce changes without breaking existing clients. This is typically done via URL versioning (e.g., /v1/users vs. /v2/users) or through custom headers. Versioning allows REST APIs to evolve over time but can lead to additional maintenance overhead as multiple versions need to be supported.
GraphQL: One of the key features of GraphQL is that it is versionless. Instead of creating new API versions when the data structure changes, GraphQL APIs evolve by adding new fields to the schema. Older fields can be deprecated and phased out without breaking existing clients, as clients only query the fields they need. This approach simplifies API evolution but requires careful planning to avoid introducing breaking changes.

Comparison: GraphQL’s versionless nature makes it easier to maintain backward compatibility and evolve APIs over time. REST requires explicit versioning, which can add complexity, especially when multiple versions need to be supported concurrently.

3.9 Tooling and Ecosystem

REST: REST has been around for a long time, and as a result, there is a rich ecosystem of tools and libraries available for building, testing, and consuming RESTful APIs. Popular tools include Postman for testing APIs, Swagger (now OpenAPI) for documentation and API design, and frameworks like Express (Node.js) and Django (Python) for building RESTful services.
GraphQL: While GraphQL is newer, its ecosystem has grown rapidly. Tools like Apollo and Relay provide client and server-side solutions for building GraphQL applications. GraphiQL and GraphQL Playground are interactive tools that allow developers to explore and test GraphQL APIs. Additionally, libraries like Prisma and Hasura offer powerful back-end solutions for creating GraphQL APIs with minimal effort.

Comparison: Both REST and GraphQL have strong ecosystems, but REST’s maturity gives it a wider selection of tools. GraphQL, however, has a growing ecosystem with many modern tools that are rapidly gaining popularity.

3.10 Learning Curve

REST: REST is relatively simple and easy to understand, especially for developers familiar with HTTP. Its reliance on standard HTTP methods and its resource-based structure make it intuitive for those who have worked with web technologies. However, complex applications can lead to challenges in managing endpoints, versioning, and performance optimizations.
GraphQL: GraphQL’s query language and schema-driven approach require a steeper learning curve. Developers need to learn how to write queries, mutations, and subscriptions, as well as understand how to work with a strongly typed schema. Additionally, the server-side implementation of GraphQL can be more complex due to query parsing, validation, and execution. However, once developers are familiar with GraphQL, its flexibility and efficiency often outweigh the initial learning effort.

Comparison: REST is easier for beginners to grasp, while GraphQL has a steeper learning curve but offers more power and flexibility once mastered.

3.11 Community and Support

REST: REST has been the standard for APIs for over a decade, and as a result, it has a vast and well-established community. There are numerous tutorials, courses, and forums where developers can find help, and most frameworks and platforms have built-in support for REST.
GraphQL: GraphQL has a rapidly growing community, but it is still relatively new compared to REST. The open-source community around GraphQL, led by tools like Apollo and Prisma, is highly active, and many large companies have adopted GraphQL (e.g., GitHub, Shopify, Twitter). As a result, the number of resources and support available is increasing.

Comparison: REST benefits from a larger, more established community, while GraphQL is growing rapidly and has strong momentum in modern web development.

4. Pros and Cons

REST Pros and Cons

Pros:

Simplicity and familiarity, especially for developers familiar with HTTP.
Rich ecosystem with mature tools for building, testing, and documenting APIs.
Built-in HTTP caching support.
Standardized error handling via HTTP status codes.

Cons:

Over-fetching and under-fetching of data.
Requires multiple endpoints and API versioning for evolving applications.
More round trips to the server for nested or related resources.

GraphQL Pros and Cons

Pros:

Flexible data fetching—clients can request exactly what they need.
Reduced network overhead through single queries for nested data.
Versionless API evolution with backward compatibility.
Strongly typed schema provides clarity and error prevention.

Cons:

Steeper learning curve for developers new to GraphQL.
More complex server-side implementation and query optimization.
No built-in HTTP caching support—requires custom caching solutions.
Potential performance risks from unoptimized or overly complex queries.

5. Use Cases and Suitability

When to Choose REST

Simple Applications: If your application has straightforward data requirements with limited nesting and relationships, REST may be the best choice due to its simplicity and ease of use.
Strong Caching Needs: REST’s built-in HTTP caching support makes it ideal for applications where cacheable resources are frequently requested.
Clear Resource Boundaries: REST is well-suited to applications where resources have well-defined, stable structures, and client requirements don’t change often.
Smaller Development Teams: For teams with limited time or experience, REST is easier to adopt, particularly due to its familiarity and extensive tooling.

When to Choose GraphQL

Complex Queries and Nested Data: Applications that need to request data from multiple related resources (e.g., fetching a user and their posts) benefit from GraphQL’s ability to fetch nested data in a single request.
Multiple Clients with Varying Data Needs: If your API serves multiple clients (e.g., web, mobile, IoT) that need different subsets of data, GraphQL’s flexibility allows each client to request only the data they need.
Real-Time Applications: GraphQL’s subscription feature makes it well-suited for real-time applications like chat apps, notifications, or live data dashboards.
Rapidly Evolving APIs: If your API’s data model changes frequently, GraphQL’s versionless nature allows you to add new fields without breaking existing clients, reducing maintenance overhead.

6. Conclusion

Choosing between REST and GraphQL ultimately depends on the specific needs of your application. REST is a tried-and-true solution that excels in simplicity, standardization, and performance in straightforward use cases. It’s a great option for smaller applications or where caching and error handling through HTTP standards are critical.

On the other hand, GraphQL shines in scenarios where flexibility, efficiency, and client-driven data fetching are key. It offers more control to the client, reduces over-fetching and under-fetching, and supports complex queries with minimal network overhead. However, it requires a deeper understanding of its architecture and can introduce server-side complexity.

In practice, many organizations use both REST and GraphQL, choosing the best approach depending on the specific requirements of their projects. The key is to evaluate the nature of your application, the complexity of data interactions, and the needs of your users when making a decision.

By understanding the trade-offs and benefits of each, you can make an informed choice that leads to better performance, maintainability, and developer productivity.

To demonstrate the REST and GraphQL approaches using the com.techsperiments base package, we will create two separate applications: one for REST and one for GraphQL. Both applications will have similar functionalities so we can compare them effectively.

For these examples, we’ll use Java with Spring Boot as the framework. We’ll assume you’re familiar with setting up a Spring Boot project. If you’re not, you can easily generate one using Spring Initializr or using tools like Maven or Gradle.

7. Practical Usage

Demo 1: REST API using Spring Boot

Application Structure

Copy codecom.techsperiments
├── model
│   └── User.java
├── repository
│   └── UserRepository.java
├── service
│   └── UserService.java
├── controller
│   └── UserController.java
└── TechsperimentsRestApplication.java

1.1 Create a Spring Boot Application

TechsperimentsRestApplication.java (Main Class)

Java

package com.techsperiments;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class TechsperimentsRestApplication {

    public static void main(String[] args) {
        SpringApplication.run(TechsperimentsRestApplication.class, args);
    }
}

1.2 Model (User Entity)

User.java (Model)

Java

package com.techsperiments.model;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // Constructors, Getters, Setters, etc.
    
    public User() {}

    public User(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

1.3 Repository (UserRepository Interface)

UserRepository.java (Repository)

Java

package com.techsperiments.repository;

import com.techsperiments.model.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
}

1.4 Service (UserService)

UserService.java (Service)

Java

package com.techsperiments.service;

import com.techsperiments.model.User;
import com.techsperiments.repository.UserRepository;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;
import java.util.Optional;

@Service
public class UserService {

    @Autowired
    private UserRepository userRepository;

    public List<User> getAllUsers() {
        return userRepository.findAll();
    }

    public Optional<User> getUserById(Long id) {
        return userRepository.findById(id);
    }

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

    public User updateUser(Long id, User userDetails) {
        Optional<User> optionalUser = userRepository.findById(id);
        if (optionalUser.isPresent()) {
            User user = optionalUser.get();
            user.setName(userDetails.getName());
            user.setEmail(userDetails.getEmail());
            return userRepository.save(user);
        }
        return null;
    }

    public void deleteUser(Long id) {
        userRepository.deleteById(id);
    }
}

1.5 Controller (UserController)

UserController.java (Controller)

Java

package com.techsperiments.controller;

import com.techsperiments.model.User;
import com.techsperiments.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;

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

    @Autowired
    private UserService userService;

    @GetMapping
    public List<User> getAllUsers() {
        return userService.getAllUsers();
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userService.getUserById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

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

    @PutMapping("/{id}")
    public ResponseEntity<User> updateUser(@PathVariable Long id, @RequestBody User userDetails) {
        User updatedUser = userService.updateUser(id, userDetails);
        return updatedUser != null ? ResponseEntity.ok(updatedUser) : ResponseEntity.notFound().build();
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
}

1.6 Client (REST Client)

Here’s a simple client using Java’s HttpClient to interact with the REST API.

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class RestClient {

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        // GET Request
        HttpRequest getRequest = HttpRequest.newBuilder()
                .uri(new URI("http://localhost:8080/api/users"))
                .GET()
                .build();
        
        HttpResponse<String> getResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());
        System.out.println("GET Response: " + getResponse.body());
        
        // POST Request
        String json = "{\"name\":\"John Doe\",\"email\":\"john.doe@example.com\"}";
        HttpRequest postRequest = HttpRequest.newBuilder()
                .uri(new URI("http://localhost:8080/api/users"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8))
                .build();
        
        HttpResponse<String> postResponse = client.send(postRequest, HttpResponse.BodyHandlers.ofString());
        System.out.println("POST Response: " + postResponse.body());
    }
}

Demo 2: GraphQL API using Spring Boot

For the GraphQL example, we’ll need to add Spring Boot GraphQL dependencies.

Application Structure

Copy codecom.techsperiments
├── model
│   └── User.java
├── repository
│   └── UserRepository.java
├── service
│   └── UserService.java
├── graphql
│   └── UserGraphQL.java
└── TechsperimentsGraphqlApplication.java

2.1 Create a Spring Boot Application

TechsperimentsGraphqlApplication.java (Main Class)

Java

package com.techsperiments;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class TechsperimentsGraphqlApplication {

    public static void main(String[] args) {
        SpringApplication.run(TechsperimentsGraphqlApplication.class, args);
    }
}

2.2 Model (User Entity)

Same as in the REST example.

2.3 Repository (UserRepository Interface)

Same as in the REST example.

2.4 Service (UserService)

Same as in the REST example.

2.5 GraphQL Schema (UserGraphQL)

UserGraphQL.java (GraphQL Resolver)

Java

package com.techsperiments.graphql;

import com.techsperiments.model.User;
import com.techsperiments.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import java.util.List;

@Component
public class UserGraphQL {

    @Autowired
    private UserService userService;

    // Query to get all users
    public List<User> getUsers() {
        return userService.getAllUsers();
    }

    // Query to get a user by ID
    public User getUserById(Long id) {
        return userService.getUserById(id).orElse(null);
    }

    // Mutation to create a new user
    public User createUser(String name, String email) {
        User user = new User();
        user.setName(name);
        user.setEmail(email);
        return userService.createUser(user);
    }
}

2.6 GraphQL Schema Definition (Schema.graphqls)

In the resources folder, create a file schema.graphqls.

Java

type User {
    id: ID
    name: String
    email: String
}

type Query {
    getUsers: [User]
    getUserById(id: ID!): User
}

type Mutation {
    createUser(name: String!, email: String!): User
}

2.7 Client (GraphQL Client)

Here’s a simple client using Java’s HttpClient to interact with the GraphQL API.

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GraphQLClient {

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        // Query Request
        String query = "{ \"query\": \"{ getUsers { id name email } }\" }";
        HttpRequest getRequest = HttpRequest.newBuilder()
                .uri(new URI("http://localhost:8080/graphql"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(query))
                .build();
        
        HttpResponse<String> getResponse = client.send(getRequest, HttpResponse.BodyHandlers.ofString());
        System.out.println("GraphQL Query Response: " + getResponse.body());
        
        // Mutation Request
        String mutation = "{ \"query\": \"mutation { createUser(name: \\\"John Doe\\\", email: \\\"john.doe@example.com\\\") { id name email } }\" }";
        HttpRequest mutationRequest = HttpRequest.newBuilder()
                .uri(new URI("http://localhost:8080/graphql"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(mutation))
                .build();
        
        HttpResponse<String> mutationResponse = client.send(mutationRequest, HttpResponse.BodyHandlers.ofString());
        System.out.println("GraphQL Mutation Response: " + mutationResponse.body());
    }
}

Summary

Both the REST and GraphQL demos follow a similar structure but with different implementations:

REST: The REST API follows the standard HTTP methods (GET, POST, PUT, DELETE) and uses separate endpoints for each action.
GraphQL: The GraphQL API offers more flexibility, allowing queries and mutations to fetch and manipulate data in a single endpoint /graphql.

These demos provide a good comparison of how the two approaches handle the same use case, giving you a foundation to understand REST and GraphQL in action.

REST vs GraphQL: Comparing and Contrasting Two API Architectures

1. What is REST?

2. What is GraphQL?

3. Comparing REST and GraphQL

3.2 Data Fetching Mechanisms

3.4 Performance

3.5 Error Handling

3.6 Caching

3.7 Security

3.8 Versioning

3.9 Tooling and Ecosystem

3.10 Learning Curve

3.11 Community and Support

4. Pros and Cons

REST Pros and Cons

GraphQL Pros and Cons

5. Use Cases and Suitability

When to Choose REST

When to Choose GraphQL

6. Conclusion

7. Practical Usage

Demo 1: REST API using Spring Boot

Application Structure

1.1 Create a Spring Boot Application

1.2 Model (User Entity)

1.3 Repository (UserRepository Interface)

1.4 Service (UserService)

1.5 Controller (UserController)

1.6 Client (REST Client)

Demo 2: GraphQL API using Spring Boot

Application Structure

2.1 Create a Spring Boot Application

2.2 Model (User Entity)

2.3 Repository (UserRepository Interface)

2.4 Service (UserService)

2.5 GraphQL Schema (UserGraphQL)

2.6 GraphQL Schema Definition (Schema.graphqls)

2.7 Client (GraphQL Client)

Summary

Comments

Leave a Reply Cancel reply