Understanding GraphQL: A Comprehensive Comparison With REST API and Its Implementation in Node.js

Understanding GraphQL: A Comprehensive Comparison With REST API and Its Implementation in Node.js

JavaScript
Fix bugs faster! Log Collection Made Easy
START NOW!

Application Programming Interface, or API, development is a critical aspect of modern software engineering, enabling diverse software systems to interact and share data seamlessly. The API serves as a contract between different software applications, outlining how they can communicate with one another.

Two of the most popular architectural styles for building Web APIs are Representational State Transfer (REST) and GraphQL. REST APIs use standard HTTP methods like GET, POST, PUT and DELETE to perform operations on data; GraphQL is a query language that allows clients to define the structure of responses for their queries and mutations, providing a more flexible approach to data interaction.

This article aims to delve into the intricacies of GraphQL, how it differs from REST API, and how you can implement it in NestJS.

The Differences Between GraphQL vs REST API

REST (Representational State Transfer), introduced by Roy Fielding in 2000, is an architectural style for networked applications. It uses a stateless, client-server communication protocol, typically HTTP, where the server provides resources and the client accesses and modifies them. REST APIs, a shift from the complex SOAP protocol, enable standardized communication between systems on the internet.

On the other hand, GraphQL, developed by Facebook in 2012 and released publicly in 2015, is a query language for APIs designed to address data loading inefficiencies in mobile networks. Unlike REST, GraphQL allows clients to specify exactly what data they need, avoiding over-fetching and under-fetching. This feature has led to its adoption by many large companies and its maintenance by the GraphQL Foundation.

Key Differences

  1. Endpoints vs. Single Endpoint: In REST you have multiple endpoints, each serving a different purpose. In GraphQL, you have a single endpoint that can handle multiple operations based on the query or mutation sent in the request.
  2. Over-fetching and under-fetching: In REST, you might end up over-fetching or under-fetching data because the server defines what data is returned for each endpoint. In GraphQL, on the other hand, you specify exactly what data you want in your query, which can help to avoid over-fetching and under-fetching.
  3. Versioning: In REST, changes to the API often lead to new versions. In GraphQL, you can avoid versioning by deprecating API fields and adding new ones.
  4. Error Handling: In REST, you can use HTTP codes to indicate the status of a request. In GraphQL, you always get a 200 OK status, and errors are handled in the response body.
  5. Data Relationships: In REST, linking related resources can be complex. In GraphQL, you can easily fetch related data in a single request using nested queries.
  6. API Discoverability: In REST, you need to refer to the documentation or the API source code to know what data can be fetched. In GraphQL, you can use tools like GraphiQL or Apollo to explore the API schema and know what data is available for fetching.

Understanding the Differences

To really grasp the differences between these two models, it’s best to use an example.

Let’s imagine we have two models for retrieving data from devices, one called Device and another called City. Here we have some example data:

Device

 {
	"id": "1",
	"imei": "1234567890",
	"address": "123 Main St",
	"name": "Device 1",
	"city_id": 1,
	"type": 1,
	"battery": 80,
	"lat": 40.7128,
	"lon": 74.0060,
	"hardware": "hardware_v1",
	"firmware": "firmware_v1",
	"comments": "This is a test device",
	"uptime": 100,
}

City

{
	"id": "1",
	"name": "New York",
	"country": "USA"
}

Query using REST API

In a REST API, you might have an endpoint to get device details:

GET /devices/:id

This might return:

{
  "id": "1",
  "imei": "1234567890",
  "address": "123 Main St",
  "name": "Device 1",
  "city_id": 1,
  "type": 1,
  "battery": 80,
  "lat": 40.7128,
  "lon": 74.0060,
  "hardware": "hardware_v1",
  "firmware": "firmware_v1",
  "comments": "This is a test device"
}

If you only needed the name, battery_main, and battery_lock of the device, you would be over-fetching data because the endpoint returns much more information than you need.

If you also needed to know the details of the city where the device is located, you would have to make another request to the City endpoint with the city_id:

GET /cities/:id

This is an example of under-fetching, because the initial request did not provide all the data you needed.

Query using GraphQL

In a GraphQL API, you could make a single request to get the exact data you need:

query {
  device(id: "1") {
    name
    battery
    city {
      name
      country
    }
  }
}

This might return:

{
  "data": {
    "device": {
      "name": "Device 1",
      "battery": 80,
      "city": {
        "name": "New York",
        "country": "USA"
      }
    }
  }
}

In this case, with a single GraphQL query, you’re getting exactly the data you need: the device’s name, main battery level, lock battery level and city details. No over-fetching, no under-fetching.

Implementing a GraphQL server API using NestJS

NestJS, a progressive Node.js framework, is an excellent choice for building efficient, scalable, and maintainable applications. It’s built with TypeScript, offering the best of both JavaScript and TypeScript features.

One of the advanced usages NestJS supports is creating GraphQL APIs. This guide will walk you through the steps to implement a GraphQL server using NestJS and Apollo.

Setting Up NestJS

Start by installing NestJS. You can use the Nest CLI, which not only sets up a new project but also helps generate application components. You can install it globally using npm:

npm i -g @nestjs/cli

Create a new project:

nest new my-graphql-project

Navigate into your new project:

cd my-graphql-project

Installing GraphQL and Apollo

For the implementation of our GraphQL API, we have decided to use Apollo Server. This is a popular and widely-used open-source solution that is community-driven and well-maintained.

By choosing Apollo Server to implement our GraphQL API, we can benefit from its many features and capabilities, including its flexibility, scalability, and ease of use. Additionally, the Apollo community provides a wealth of resources and support, which can help us to quickly and effectively implement our API. With all of these factors in mind, we can be confident that Apollo Server is the ideal choice for our needs.

Let’s start by installing all the necessary dependencies:

npm i @nestjs/graphql @nestjs/apollo @apollo/server graphql

Now we need to import Apollo into the App module, which you can configure by choosing certain key options.

In our case, we are going to use autoSchemaFile: truebecause we are using a code-first approach to define our API (we use decorators and TypeScript classes to generate the corresponding GraphQL schema). We also disable the default GraphQL playground to use Apollo Server, which offers more funcionality and has a more user-friendly UI.

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { GraphQLModule } from '@nestjs/graphql';
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { ApolloServerPluginLandingPageLocalDefault } from '@apollo/server/plugin/landingPage/default';

@Module({
  imports: [
    GraphQLModule.forRoot<ApolloDriverConfig>({
      driver: ApolloDriver,
			autoSchemaFile: true,
			playground: false,
      plugins: [ApolloServerPluginLandingPageLocalDefault()],
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule { }

Creating a GraphQL Module

In NestJS, modules provide a great way to organize your code. You can create a GraphQL module with the following code:

nest generate module devices

This command creates a new module and registers it in app.module.ts.

Defining a GraphQL Schema

In GraphQL, the schema is the centerpiece of your API. It defines the shape of your data and the operations available. In NestJS, you define your schema using TypeScript classes and decorators.

You can create a device schema in a device/entities/device.entity.ts file with the following code:

import { ObjectType, Field, Int } from '@nestjs/graphql';

@ObjectType()
export class Device {
	@Field(() => String, { description: 'Device ID' })
	id: string;

	@Field(() => String, { nullable: true })
	imei: string;

	@Field(() => String, { nullable: true })
	address: string;

	@Field(() => String, { nullable: true })
	name: string;

	@Field(type => Int, { nullable: true })
	city_id: number;

	@Field(() => Number, { nullable: true })
	type: number;

	@Field(() => Number, { nullable: true })
	battery: number;

	@Field(() => Number, { nullable: true })
	lat: number;

	@Field(() => Number, { nullable: true })
	lon: number;

	@Field(() => String, { nullable: true })
	hardware: string;

	@Field(() => String, { nullable: true })
	firmware: string;

	@Field(() => String, { nullable: true })
	comments: string;
}

Creating a Resolver and a Service

Resolvers are the equivalent of controllers in REST. They handle the incoming queries and mutations and do the required operations. To create a devices resolver in devices/devices.resolver.ts, use the following code.

nest generate resolver devices

In the devices.resolver.ts file, define a query to get a device:

import { Query, Resolver } from '@nestjs/graphql';
import { Device } from './entities/device.entity';
import { DevicesService } from './devices.service';

@Resolver()
export class DevicesResolver {
  constructor(private readonly devicesService: DevicesService) { }

	@Query(() => [Device], { name: 'devices' })
	findAll() {
		return this.devicesService.findAll();
	}
}

As you can see, the resolver ends by calling a function of DevicesService, as we use Services to abstract the data manipulation layer. Let’s write this file now.

nest generate service devices

In the devices.service.ts file, you can define the function to get the devices from your data repository. In our example we return a hardcoded device, but the most common use case will use TypeORM to query a database.

import { Injectable } from '@nestjs/common';

@Injectable()
export class DevicesService {
    findAll() {
		return new Array({
            id: '1',
            imei: '123456789012345',
            address: '123 Main St',
            name: 'My Device',
            city_id: 1,
            type: 1,
            battery: 100,
            lat: 0,
            lon: 0,
            hardware: '1.0',
            firmware: '1.0',
            comments: 'This is a comment'            
        });
    }
}

Testing Your API

Write the following to start your server:

npm run start

Navigate to http://localhost:3000/graphql in your browser. You’ll see the Apollo GraphQL explorer and playground, where you can list all your queries and mutations and test your API. As you can see, there’s only a single GraphQL endpoint, not multiple endpoints as in a RestAPI.

On the left-hand side you will see all the queries defined in your API. The middle section shows the current query you want to try, and the right-hand section shows the response from the server. You can play around as the UI is very intuitive.

Here you have a query that fetches the id, name and address of the devices, and shows how the server responds with the data.

Here you can clearly see the flexibility of GraphQL versus Rest API. You can define which fields you can query instead of getting a fixed number of fields on a Rest API; you can even add relationships to the query.

GraphQL Mutations

The next step after defining a GraphQL schema and testing out our first query is to implement mutations, functions that allow you to create, update, or delete data on the server.

In the case of our devices API, we might have mutations that allow us to create, update, or delete devices. Let’s create an example mutation, which involves creating a new device with a specific set of properties.

First we create and Input the entity to define which data is required to create a device (we create a simple mutation that allows us to create a device with only the imei field and optionally a name). So let’s create the file devices/dto/create-device.input.ts:

import { InputType, Int, Field } from '@nestjs/graphql';

@InputType()
export class CreateDeviceInput {
	@Field(() => String, { description: 'Device IMEI', nullable: false })
  imei: String

	@Field(() => String, { description: 'Device Name', nullable: true })
  name: String!
}

Now we add a mutation operation in our devices.resolver.ts:

import { Query, Resolver } from '@nestjs/graphql';
import { Device } from './entities/device.entity';
import { DevicesService } from './devices.service';

@Resolver()
export class DevicesResolver {
  constructor(private readonly devicesService: DevicesService) { }

	@Query(() => [Device], { name: 'devices' })
	findAll() {
		return this.devicesService.findAll();
	}

	@Mutation(() => Device)
	createDevice(@Args('createDeviceInput') createDeviceInput: CreateDeviceInput) {
		return this.devicesService.create(createDeviceInput);
	}
}

And finally, you can modify the devices.service.ts file to add the new function, and add the new database to your current underlying data storage service. However this function is out of the scope of this article, as we are focusing on understanding how GraphQL works.

Frequently Asked Questions: GraphQL vs REST API

What is the main difference between GraphQL and REST API?

GraphQL is a query language that allows clients to determine the form of replies for their queries and changes, making data interaction more flexible. REST APIs, on the other hand, perform data operations using normal HTTP methods such as GET, POST, PUT, and DELETE.

Why would one choose GraphQL over RESTful API?

GraphQL provides benefits such as a single endpoint for numerous actions, precise data retrieval without over- or under-fetching, and the ability to retrieve related data in a single request via nested queries. Versioning, which is common in REST, is likewise eliminated.

Is GraphQL more efficient than REST API?

When clients require specialized data structures or when there is a requirement to avoid over-fetching and under-fetching of data, GraphQL can be more efficient. However, efficiency is also affected by implementation and use case.

When was GraphQL introduced and by whom?

GraphQL was created by Facebook in 2012 and made public in 2015. It was created to solve inefficiencies in data loading on mobile networks.

How does error handling differ between GraphQL and REST API?

Different HTTP codes are used in REST to indicate the status of a request. GraphQL, on the other hand, always returns a 200 OK status, and errors are handled within the response body, providing greater details about the exact error.

How does GraphQL handle API versioning compared to REST?

One of the key benefits of GraphQL is that it can eliminate the need for versioning. Developers can deprecate API fields and introduce new ones instead of generating new versions of the API, ensuring compatibility with previous versions.

What is a GraphQL schema?

A GraphQL schema describes the data types and structures that can be queried and transformed. It acts as a contract between the client and the server, defining how the client can request data and the structure of the the outcome.

Which technologies are popular for creating a GraphQL server?

A GraphQL server can be built using a wide range of technologies. Some of the most popular are Apollo Server, Express-GraphQL, and Prisma. The technology used is frequently determined by the project’s specific requirements and the developer’s expertise with the toolset.

What is a GraphQL query?

GraphQL queries, which enable accurate data retrieval from a GraphQL server, are an essential part of the GraphQL query language. It characterizes itself by its data interaction versatility, allowing clients to determine the exact form of their desired result. This ensures that clients only receive the data they require, making it a critical aspect in the comparison between GraphQL and REST API.

Conclusion

The implementation of a GraphQL API using NestJS offers a robust, efficient solution for modern API development. With its modular structure and use of TypeScript, NestJS provides a solid foundation for building scalable applications.

Using a GraphQL API can help eliminate common issues associated with REST APIs, such as over-fetching and under-fetching, and remove the need for versioning. The single endpoint in GraphQL simplifies the client-server interaction, and the capability to fetch related data in a single request makes it a powerful tool for dealing with complex data relationships.

The combination of NestJS and GraphQL provides developers with a powerful toolkit for building efficient, scalable, and maintainable APIs. Whether you’re building a small application or a large-scale system, this combination can help you meet your development goals effectively and efficiently.

For your project, you may need a database. If so, you can read the following article where we discuss database services:

Top 9 Database-as-a-Service Products

In subsequent articles, we will learn how to query GraphQL on different frontend development platforms. Here you have some of the articles on how to use your GraphQL on your app:

Expect the Unexpected! Debug Faster with Bugfender
START FOR FREE

Trusted By

/assets/images/svg/customers/highprofile/rakuten.svg/assets/images/svg/customers/highprofile/credito_agricola.svg/assets/images/svg/customers/projects/menshealth.svg/assets/images/svg/customers/cool/websummit.svg/assets/images/svg/customers/cool/riachuelo.svg/assets/images/svg/customers/highprofile/schneider_electric.svg/assets/images/svg/customers/projects/sk_telecom.svg/assets/images/svg/customers/highprofile/oracle.svg

Already Trusted by Thousands

Bugfender is the best remote logger for mobile and web apps.

Get Started for Free, No Credit Card Required