Coder Legion - Recent posts tagged graphql

How to Decide Whether a WAF Can Protect a GraphQL API

Thu, 22 Oct 2026 08:00:23 +0000

Protecting a GraphQL API with a WAF starts with an honest inventory of the HTTP conversation, not with a claim that the firewall understands your schema. SafeLine is a self-hosted web application firewall that filters and monitors HTTP traffic between a web application and the Internet, and it works as a reverse proxy so clients reach the shield before they reach the origin (https://docs.waf.chaitin.com/en/home). The same product docs describe it as an HTTP and HTTPS reverse proxy built on nginx: it receives traffic for the original site, cleans malicious traffic, and forwards the remaining traffic upstream (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). Those pages do not describe a GraphQL parser, query-depth limit, complexity budget, or persisted-query allowlist. This checklist is the decision guide I use when the question is how to protect a GraphQL API with a WAF and the product evidence only covers general HTTP controls.

Start with the listener, not the resolvers. In the SafeLine console, an application is defined by a domain, hostname, or IP, a listen port such as 80 or 443, an SSL option for HTTPS apps, and an upstream address that receives forwarded traffic (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). After that, the domain must resolve to the SafeLine server. For GraphQL, write down the exact path, methods, and content types your clients use. A browser app that posts JSON to a single endpoint is a different operational problem from a partner integration that posts the same shape from a server. Both are still HTTP. Neither fact, by itself, means SafeLine will interpret operation names.

Separate controls that belong in the API from controls the WAF documents. Field authorization, introspection policy, alias limits, depth limits, and cost analysis have to live in the GraphQL server or gateway. Do not treat a missing integration note as a hidden feature. What the WAF docs do list is broader web-attack defense, proactive bot-abuse defense, HTML and JS code encryption, IP-based rate limiting, and a web access control list (https://docs.waf.chaitin.com/en/home). The attack list includes SQL injection, XSS, code injection, OS command injection, CRLF injection, LDAP injection, XPath injection, RCE, XXE, SSRF, path traversal, backdoor, brute force, HTTP flood, and bot abuse. Those checks can matter when a GraphQL variable carries a classic payload, because the bytes still travel in an HTTP request. They are not a substitute for resolver authorization, and they do not prove that every malicious query will be recognized as GraphQL abuse.

Use rate limiting where the abuse is volume, not query shape. SafeLine rate limiting is documented as a way to throttle traffic that exceeds defined limits, including DoS, brute-force attempts, traffic surges, and other abuse (https://docs.waf.chaitin.com/en/home). That is a reasonable layer in front of a login mutation or a hot query path that is being flooded. It does not count field complexity. If one small request can expand into thousands of resolver calls, fix that in the API even if the firewall never raises an alarm.

Be careful with challenges. CAPTCHA is documented to allow human users and block crawlers and bots. An authentication challenge, when turned on, requires visitors to enter a password or be blocked (https://docs.waf.chaitin.com/en/home). Those controls can fit a browser-only GraphQL console. They can break mobile apps, server jobs, and other non-browser clients. Put that client inventory on the checklist before you enable either challenge on the API host. Dynamic protection, which encrypts HTML and JS on each visit, is also documented (https://docs.waf.chaitin.com/en/home). A pure JSON GraphQL response is not an HTML or JS page, so do not plan on that feature as API protection.

Validate with the tests the docs actually publish, then read the console. The application guide shows sample requests for SQL injection, XSS, path traversal, code injection, and XXE, and says a blocking page means the attack was defended. Attack detail is available in the web console (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). You can repeat the same payload classes inside a GraphQL variable as a manual check that the HTTP body is visible to inspection. A block is evidence about that payload, not evidence of schema-aware coverage. A pass is not proof that the query is safe.

Check the host before cutover. The install guide requires Linux, x86_64 or arm64, Docker 20.10.14 or above, Docker Compose 2.0.0 or above, and at least 1 CPU core, 1 GB of memory, and 5 GB of disk, plus a CPU with ssse3 (https://docs.waf.chaitin.com/en/GetStarted/Deploy). The same page says SafeLine on ARM requires a Pro license and that the Personal Edition is not supported on ARM. The product home page states that SafeLine is production-ready, with over 180,000 installations, protection for over 1,000,000 websites, and more than 30,000,000,000 HTTP requests handled daily (https://docs.waf.chaitin.com/en/home). As of September 30, 2026, SafeLine surpassed 700,000 installations worldwide. SafeLine Pro annual promotional pricing is $650-$880 versus the $1,000 regular price.

If the checklist fails at any point where you needed a GraphQL-specific control, keep that control in the API. Use the WAF for the HTTP jobs its docs describe: reverse-proxy placement, attack filtering, rate limiting, access control, and optional human challenges on browser traffic.

Does SafeLine document a GraphQL rule pack?

No. The supplied product docs describe general HTTP and HTTPS filtering, reverse-proxy application setup, and the controls listed above. They do not document GraphQL query parsing, depth limits, or complexity scoring. Plan those in the API.

Should every GraphQL client pass a CAPTCHA?

No. CAPTCHA and the authentication challenge are documented visitor checks. They fit some browser flows and can block legitimate non-browser clients. Decide from your client list, not from a generic API template.

Is IP rate limiting enough for an expensive query?

No. Documented rate limiting throttles traffic that exceeds defined limits. It does not measure resolver cost. Keep complexity limits in the GraphQL server, and use rate limiting for floods and brute force.

What do I check after the domain points at SafeLine?

Confirm domain, port, SSL choice, and upstream in the application dialog, then confirm clients still reach the origin only through the proxy (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). Review the attack list when you replay the documented test payloads. Treat GraphQL-only abuse cases as API tests, not as undocumented firewall features.

If you want a second pair of eyes on this checklist before cutover, review the project and the official docs, then compare the current Pro promotion with your deployment constraints.

Project: https://github.com/chaitin/SafeLine
Docs: https://docs.waf.chaitin.com/en/home
Promotion: https://cyberserval.tech/landing/lto

How to Decide If a WAF Belongs in Front of GraphQL

Thu, 22 Oct 2026 07:59:52 +0000

A GraphQL API is still an HTTP application with a narrow front door. Most deployments expose one path, accept a document plus variables, and return JSON. That shape invites two mistakes: leaving the origin directly reachable, or assuming a web application firewall understands selections, fragments, and resolver cost. This checklist uses only controls described in the SafeLine documentation. Where those pages are silent, the item stays on the API, not in the proxy.

SafeLine is a self-hosted WAF. It filters and monitors HTTP traffic and is designed to block common web attacks, including SQL injection, XSS, code injection, OS command injection, CRLF injection, LDAP injection, XPath injection, RCE, XXE, SSRF, path traversal, backdoors, brute force, HTTP flood, and bot abuse (https://docs.waf.chaitin.com/en/home). It works as a reverse proxy: clients pass through it before they reach the server, and it forwards traffic it does not treat as malicious (https://docs.waf.chaitin.com/en/GetStarted/AddApplication). Nothing on those pages describes a GraphQL parser, an introspection switch, a complexity score, or a persisted-query catalog. If you need those, build them in the GraphQL server. A WAF placement is still worth a decision, because the same endpoint is ordinary HTTP and can carry injection payloads in headers, query strings, and bodies.

Placement checklist

Work through these gates before you change a production record.

Confirm the protocol. SafeLine protects web apps by proxying HTTP and HTTPS. If the API is not reached that way, stop. Do not invent a side integration.
Pick the hostname clients already trust. In Applications, Add Application asks for Domain, Port, and Upstream. Use 443 and enable SSL for HTTPS, or 80 for plain HTTP. Upstream is the real address of the GraphQL process. After saving, resolve that domain to the SafeLine server so clients never need the origin address (https://docs.waf.chaitin.com/en/GetStarted/AddApplication).
Map each fear to a documented control. Injection and related web attacks map to the attack defenses above. Floods, brute force, and traffic surges map to rate limiting, which the docs describe as throttling traffic that exceeds defined limits, and the core list calls out IP-based rate limiting (https://docs.waf.chaitin.com/en/home). A web access control list is also named there. Do not write rule syntax the guides do not provide; configure it in the console and verify the result.
Treat human challenges as optional, not as API authentication. Captcha is documented to allow human users and block crawlers and bots. Authentication challenge blocks visitors who do not enter the password. Either can shield a browser IDE pointed at /graphql. Either can also black-hole a mobile client or a partner job. If no human is in the loop, leave both off.
Skip dynamic HTML and JS encryption for a JSON API. That feature encrypts HTML and JS on each visit. It is not a control for GraphQL documents or JSON responses.
Match the host to the install guide before the pilot. You need Linux on x86_64 or arm64, Docker 20.10.14 or newer, Docker Compose 2.0.0 or newer, at least one CPU core, 1 GB of memory, 5 GB of disk, and a CPU with SSSE3 (https://docs.waf.chaitin.com/en/GetStarted/Deploy). On ARM, a Pro license is required; the Personal Edition is not supported on ARM. The same page notes that the LTS line is no longer maintained starting from 9.1.0-LTS on 14 August 2025, and recommends the current release for new setups.
Prove the path with the published probes, then with your own POST. The application guide lists SQL injection, XSS, path traversal, code injection, and XXE samples as query strings, and tells you to expect a block page and to open the attack detail in the console. Run those against a test hostname. Then send a normal GraphQL query, a mutation, and a deliberately hostile string inside a variable. A query-string block does not, by itself, prove how a JSON body will be classified. The console is the evidence, not a guess.
Keep schema policy at the origin. Depth limits, alias and batch ceilings, field authorization, and introspection policy are application concerns. SafeLine is not documented as a GraphQL gateway. Putting it in front does not authorize you to delete those checks.

Rate limits need a GraphQL-specific reading even though the feature is generic. One route receives almost every operation, so a low ceiling can punish a busy office NAT or a single backend egress address. Start from real client-IP rates, then tighten. Review the attack list after the change so a false block is visible before customers report it.

The home documentation calls the product production-ready, protecting over 1,000,000 websites and handling over 30,000,000,000 HTTP requests daily, and it publishes a general detection evaluation on 33,669 samples (https://docs.waf.chaitin.com/en/home). Those numbers are not a GraphQL score. Do not reuse them as one. As of September 30, 2026, SafeLine surpassed 700,000 installations worldwide. SafeLine Pro annual promotional pricing is $650-$880 versus the $1,000 regular price.

Does the documentation describe GraphQL body parsing?

No. It describes HTTP and HTTPS reverse-proxy filtering and a list of web-attack defenses. Plan for that, and test a real POST, instead of assuming a schema-aware inspection engine.

Where do clients send GraphQL after cutover?

They send it to the domain you added in Applications. That domain must resolve to the SafeLine host. SafeLine forwards cleaned traffic to the upstream you configured.

Can captcha replace API keys?

No. Captcha and the authentication challenge are visitor gates for humans and bots, as documented. Credential checks for apps, jobs, and partners still belong to your API.

What fails an install before GraphQL is even involved?

A host that misses the Docker, Compose, CPU, memory, disk, or SSSE3 requirements will not match the install guide. An ARM host without a Pro license is also the wrong pilot target, because the Personal Edition is not supported on ARM.

What should the first success metric be?

A documented attack sample blocked on a test hostname, a visible detail record in the console, and a legitimate GraphQL operation from a real client that still succeeds. Adoption of the proxy is not proof that resolver cost is under control.

If you are about to publish a GraphQL endpoint, walk this checklist, install from the official guide, and add the application before you argue about schema limits. As of September 30, 2026, SafeLine surpassed 700,000 installations worldwide. SafeLine Pro annual promotional pricing is $650-$880 versus the $1,000 regular price. You can review the project, the docs, and the current promotion here:

https://github.com/chaitin/SafeLine

https://docs.waf.chaitin.com/en/home

https://cyberserval.tech/landing/lto

Getting Started with GraphQL in ASP.NET

Tue, 04 Aug 2026 08:44:29 +0000

Getting Started with GraphQL in ASP.NET and EF Core

GraphQL is a modern API technology that allows clients to request exactly the data they need. Unlike traditional REST APIs, GraphQL uses a single endpoint and gives consumers more control over the response structure.

If you're building ASP.NET applications with Entity Framework Core, adding GraphQL can be a great way to expose your data efficiently.

Why GraphQL?

With REST APIs, clients often receive more data than they need or must call multiple endpoints to collect related information.

GraphQL helps solve these problems by providing:

Flexible data retrieval
Fewer API requests
Strongly typed schemas
Better performance for complex data scenarios

Create a New ASP.NET Project

Start by creating a Web API project:

dotnet new webapi -n GraphQLDemo
cd GraphQLDemo

Install the required packages:

dotnet add package HotChocolate.AspNetCore
dotnet add package HotChocolate.Data.EntityFramework
dotnet add package Microsoft.EntityFrameworkCore.InMemory

Create the Entity

Let's create a simple Product model:

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

Configure EF Core

Create a DbContext:

using Microsoft.EntityFrameworkCore;

public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options)
        : base(options)
    {
    }

    public DbSet<Product> Products => Set<Product>();
}

Create a GraphQL Query

GraphQL queries define the data clients can request.

public class Query
{
    public IQueryable<Product> GetProducts(
        [Service] AppDbContext context)
    {
        return context.Products;
    }
}

Returning IQueryable allows Hot Chocolate to optimize filtering, sorting, and projections.

In Program.cs:

using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseInMemoryDatabase("ProductsDb"));

builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>();

var app = builder.Build();

using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();

    db.Products.AddRange(
        new Product { Id = 1, Name = "Laptop", Price = 999.99m },
        new Product { Id = 2, Name = "Mouse", Price = 29.99m }
    );

    db.SaveChanges();
}

app.MapGraphQL();

app.Run();

Run Your First Query

Navigate to:

https://localhost:5001/graphql

Execute:

query {
  products {
    id
    name
    price
  }
}

Response:

{
  "data": {
    "products": [
      {
        "id": 1,
        "name": "Laptop",
        "price": 999.99
      },
      {
        "id": 2,
        "name": "Mouse",
        "price": 29.99
      }
    ]
  }
}

Enable Filtering and Sorting

One of the best features of Hot Chocolate is built-in filtering and sorting.

Update the query:

using HotChocolate.Data;

public class Query
{
    [UseFiltering]
    [UseSorting]
    public IQueryable<Product> GetProducts(
        [Service] AppDbContext context)
    {
        return context.Products;
    }
}

builder.Services
    .AddGraphQLServer()
    .AddQueryType<Query>()
    .AddFiltering()
    .AddSorting();

Now clients can run queries like:

query {
  products(
    where: { price: { gt: 100 } }
    order: { price: DESC }
  ) {
    name
    price
  }
}

Conclusion

GraphQL and EF Core work very well together in ASP.NET applications. With Hot Chocolate, you can expose database entities through GraphQL with minimal configuration while gaining powerful features like filtering, sorting, and projections.

If you're already using EF Core, adding GraphQL is an easy way to make your APIs more flexible and developer-friendly. Start with simple queries, then move on to mutations, authentication, and real database providers like SQL Server or PostgreSQL.

Happy coding! 🚀

References

GraphQL Official Documentation, Learn GraphQL

https://graphql.org/learn/

GraphQL Official Documentation, Queries

https://graphql.org/learn/queries/

Hot Chocolate Documentation, Getting Started with GraphQL in .NET

https://chillicream.com/docs/hotchocolate/get-started-with-graphql-in-net-core

Hot Chocolate Documentation, GraphQL Server for .NET
https://chillicream.com/docs/hotchocolate

Getting Started with GraphQL for Laravel Developers

Mon, 23 Feb 2026 06:56:26 +0000

Unlock the potential of GraphQL in your Laravel applications. This guide covers the fundamentals, advantages over REST, and practical ways to integrate GraphQL into your projects.

Introduction to GraphQL

GraphQL is a powerful query language for APIs, initially developed by Facebook. Unlike REST, which exposes multiple endpoints, GraphQL provides a single endpoint. Here, you can request only the data you need, reducing payload size and improving speed.

Architecture of GraphQL

At its core, GraphQL is built around the concepts of types and fields. You define a schema that describes what queries can be made and what types of data each query returns. This schema acts as a contract between the client and the server.

Key Components of GraphQL:

Queries: Read data.
Mutations: Write data.
Subscriptions: Listen to real-time updates.

Advantages Over REST

Single Endpoint: Eliminate the need for multiple URLs, streamlining your API.
Client-Driven: Clients request exactly what they need, minimizing over-fetching and under-fetching.
Strongly Typed: Changes to the data structure can be managed more easily due to the schema definition.

Getting Started

Integrating GraphQL with Laravel

To start using GraphQL in your Laravel application, follow these steps:

Install the Package:
You can use the lighthouse-php package, which is a popular choice for integrating GraphQL in Laravel:
```
composer require nuwave/lighthouse
```
Publish the Config File:
Run the following command:
```
php artisan vendor:publish --tag=lighthouse
```
Define Your Schema:
Create a graphql/schema.graphql file. Here’s a simple example:
```
type Query {
    users: [User]
}
type User {
    id: ID!
    name: String!
}
```

Create Resolvers:
For the users query, you might set up a resolver in app/GraphQL/Queries/UserQuery.php:

namespace App\GraphQL\Queries;
use App\Models\User;
   
class UserQuery {
    public function resolve($root, array $args) {
        return User::all();
    }
}

Testing Your GraphQL API:
You can use tools like Postman or GraphQL Playground to play around with your API. Here’s a simple query to get started:
```
query {
    users {
        id
        name
    }
}
```

Conclusion

GraphQL offers a flexible way to interact with your data, which can improve performance and reduce the time it takes to build features. By adopting these principles, you can create APIs that better serve the needs of your applications. Start experimenting, and you might find that GraphQL changes how you think about API design altogether.

End-to-End GraphQL File Uploads with Apollo Server and Apollo Client: A Comprehensive Guide

Sat, 30 Aug 2025 11:10:34 +0000

We recently started partnering (where I currently work) with some of our customers to co-create content, and as a result we needed a way to stream files from the client to the server, through GraphQL. This added an extra layer of complexity, which took us some time to effectively hash-out, and hence the inspiration for this blog.

In this blog, I'll be walking you through (with code snippets included) how to enhance your GraphQL set up, to allow for file uploads. I intend this tutorial to be an in-depth one, that goes full circle starting with the server set up, and implementation (using Apollo Server), and going all the way to the client set up and implementation (using Apollo Client).
The tech-stack specifications for the client will be Apollo client (and I'll try and generalize the config as much as possible since there's a gazillion javascript frontend frameworks and I can't possibly touch on all of them. There'll be probably another new javascript frontend framework by the time you are reading this lol).
For the server, the set-up is mostly inclined towards NestJS, but can be co-adopted to other frameworks as well.

1. Spinning Up the Backend: Dependencies & Configuration

So for starters, create a nestjs project (if you don't have one already). You can skip this step if you have your own set-up that isn't nestjs-related.

nest new project-name

Secondly, install necessary dependencies (I'm using TypeScript, which should - at the risk of breaking the one forbidden software rule of having an opinion - be your default at this point. If you are writing server-side code without static types, then you must be the one-true master, and I'd love to learn your ways). Skip the nestjs apollo dependencies if you have a different backend set up:

npm i @nestjs/graphql @nestjs/apollo @apollo/server@^4.11.2 graphql graphql-upload-ts

Next, we need to configure our graphql set-up.

For the nestjs category:

Open app.module.ts and make sure your graphql config matches mine (especially since v10 of Apollo Server removed it's built-in upload handler):

// ...other imports
import { ApolloDriver, ApolloDriverConfig } from '@nestjs/apollo';
import { ApolloServerPluginLandingPageLocalDefault } from '@apollo/server/plugin/landingPage/default';
// ...other imports
GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  playground: false, // Let's get fancy with an alternative playground.
  plugins: [
    ApolloServerPluginLandingPageLocalDefault({
      embed: true,
    }),
  ],
  uploads: false, // Disable Apollo’s default upload handling if on NestJS 9+ (and Apollo Server version 10 and above).
  autoSchemaFile: 'src/schema.gql', // Adjust if your path differs!
  sortSchema: true,
  introspection: true,
  context: ({ req, res }) => ({ req, res }),
})
// ...other imports

Then configure the graphqlUploadExpress middleware within the same app.module.ts file:

export class GraphQLAppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer
      .apply(
      // apply the upload middleware, setting reasonable defaults.
        graphqlUploadExpress({
          maxFieldSize:100 * 1024 * 1024, // 100MB
          maxFileSize: 100 * 1024 * 1024, // 100MB
          maxFiles: 10, // 10 files per request
        })
      )
      .forRoutes('graphql');
  }
}

for the bare-metal express server category:

const express = require('express');
const expressGraphql = require('express-graphql');
const { graphqlUploadExpress } = require('graphql-upload-ts');

express()
  .use(
    '/graphql',
    // apply the upload middleware, setting reasonable defaults.
    graphqlUploadExpress({
      maxFieldSize:100 * 1024 * 1024, // 100MB
      maxFileSize: 100 * 1024 * 1024, // 100MB
      maxFiles: 10, // 10 files per request
    }),
    // Replace with your schema path
    expressGraphql({ schema: require('./schema.gql') })
  )
  .listen(3000);

2. Server Models, DTOs, & Resolvers: Building Your Upload Endpoint

Next, we'll define our model, which we'll call BigFileDataModel.
For nestjs users, I'm using the code-first approach. For the rest of the readers, I'll also include a snippet of the resulting schema to include in your schema files.

The typescript definition:

import { Field, InputType } from '@nestjs/graphql';
import { FileUpload, GraphQLUpload } from 'graphql-upload-ts';
import { IsIn, IsNotEmpty } from 'class-validator';

@InputType()
export class BigFileDataModel {
  @Field()
  @IsNotEmpty()
  @IsIn(['mp4', 'mov', 'avi', 'mkv', 'webp', 'jpeg', 'jpg', 'png'])
  fileType: string;

  @Field(() => GraphQLUpload)
  contents: Promise<FileUpload>;
}

The equivalent schema:

"""The `Upload` scalar type represents a file upload."""
scalar Upload

input BigFileDataModel {
  contents: Upload!
  fileType: String!
}

Our BigFileDataModel has a file type and contents. The fileType is the file extension (so .png, .jpg and so on), and the contents is the binary file itself.

A quick thing to note: Make sure the data types match the typescript example if you are using schema-first approach, specifically the contents (which will be the file being streamed), which returns a promise when all the file bytes have finished transmitting.

Request & Response DTOs

Next, we'll create our DTOs that will be used by a resolver (which we'll create in a future step).
The DTOs will be basically a request and response DTO (Data Transfer Object).
For nestjs readers using the code-first approach, here's the TypeScript definitions.

Our Request DTO:
Request DTO:

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

@ArgsType()
export class UploadFileRequest {
  @Field(() => BigFileDataModel)
  file: BigFileDataModel;
}

Response DTO:

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

@ObjectType()
export class _UploadFileResponse {
  @Field({ nullable: true })
  file: string;
}

// Use your preferred base response structure, here I'm assuming inheritance/mixins:
@ObjectType()
export class UploadFileResponse extends StandardGraphQLResponse(_UploadFileResponse) {}

For our schema-first readers, here's the equivalent schema:

"""The `Upload` scalar type represents a file upload."""
scalar Upload

input BigFileDataModel {
  contents: Upload!
  fileType: String!
}

"""The section above has been included from a previous step for consistency """

type UploadFileResponse {
  file: String!
}

type Mutation {
  uploadFile(file: BigFileDataModel!): UploadFileResponse!
}

The request DTO basically takes an argument file which specifies the file properties we are sending from the client.

Our Resolver and FileUploadService class

At this point I don't think I need a 'nestjs code-first approach users' and 'schema-first users'. I assume you'll be smart enough to deduce which code snippet is for you moving forward.

Our typescript resolver (feel free to adapt this without the annotations to your resolver definition):

import { Resolver, Mutation, Args } from '@nestjs/graphql';

@Resolver('FileUploadResolver')
export class FileUploadResolver {
  constructor(private readonly fileUploadService: FileUploadService) {}

  @Mutation(() => UploadFileResponse)
  async uploadFile(@Args() req: UploadFileRequest) {
    const res = await this.fileUploadService.uploadToFirebase({
      file: req.file.contents,
      fileType: req.file.fileType,
    });
    return { file: res };
  }
}

The resolver basically calls our file upload service (which uploads the binary file to Google Storage, and returns a string representing the public url).

Here's the definition of our FileUploadService.ts, which you can feel free to re-use in your personal services requiring file upload.

import { Injectable } from '@nestjs/common';
import { Readable } from 'stream';
import { FileUpload } from 'graphql-upload-ts';

@Injectable()
export class FileUploadService {
  constructor(private readonly folderName: string) {}

  async uploadToFirebase({
    file,
    fileType,
  }: {
    file: Promise<FileUpload>;
    fileType?: string;
  }): Promise<string> {
    const buffer = await this.streamToBuffer((await file).createReadStream());
    const _fileName = `${Date.now()}-${Math.round(Math.random() * 1e9)}.${fileType}`;
    
    // Check the definition for this method below
    return await this.saveFileToStorage(this.folderName, _fileName, buffer);
  }

  private async streamToBuffer(readableStream: Readable): Promise<Buffer> {
    return new Promise((resolve, reject) => {
      const chunks: Buffer[] = [];
      readableStream.on('data', (data) => {
        if (typeof data === 'string') {
          chunks.push(Buffer.from(data, 'utf-8'));
        } else {
          chunks.push(data);
        }
      });
      readableStream.on('end', () => resolve(Buffer.concat(chunks)));
      readableStream.on('error', reject);
    });
  }

  // Stub: wire this up to your favorite storage backend
  private async saveFileToStorage(folder: string, fileName: string, buffer: Buffer): Promise<string> {
    // Implementation left as an exercise for the reader. Feel free to user Google storage/S3/local-fs or your own implementation for this.
    return `https://storage.example.com/${folder}/${fileName}`;
  }
}

There you have it - we have our server set up and ready to receive graphql file uploads. You can stop here if you're a just-backend engineer and hate anything to do with HTML/CSS/JavaScript.

For our full-stack engineers (yes, you rank higher than the just-backend engineers) who also want to set up a client, read on.

3. Client-Side Wizardry: Uploading Files with Apollo Client

Let's face it: JavaScript frontend frameworks multiply like rabbits. As a result, I'll try my best to keep the client implementation as framework-agnostic as possible. I'll use Apollo Client as an agnostic toolkit (since it's a separate implementation that does not depend on any frameworks, and is in the blog title).

Install necessary dependencies:

npm install @apollo/client apollo-upload-client

Setup Apollo Client Setup (with Upload)

Set up your Apollo Client (which you can use in your ApolloProvider in the case of Next.js. For other frameworks, you're on your own here):

import { ApolloClient, InMemoryCache } from '@apollo/client';
import { createUploadLink } from 'apollo-upload-client';
import { setContext } from '@apollo/client/link/context';

const httpLink = createUploadLink({
  uri: 'http://localhost:4000/graphql', // Plug in your server URL!
});

const headersLink = setContext((_, { headers }) => ({
  headers: {
    ...headers,
    'Apollo-Require-Preflight': 'true', // Enable CORS for file uploads
  },
}));

const apolloClient = new ApolloClient({
  cache: new InMemoryCache(),
  link: headersLink.concat(httpLink),
  ssrMode: typeof window === 'undefined', // Server-side support, if needed
});

export default apolloClient;

In the example above, we create two links: one for injecting headers, and the other, a http terminating link for file upload, provided by the apollo-upload-client package.
Then we include the 'Apollo-Require-Preflight': 'true' header, which is needed for enabling cors. This is outside the scope of this tutorial, but if you'd like to find out more, you can here;

The GraphQL Mutation

mutation uploadFile($file: BigFileDataModel!) {
  uploadFile(file: $file) {
    file
  }
}

File Input and Upload Logic

Here’s a barebones React-flavored file uploader. You can adapt this for your front-end framework of choice.

import { useMutation } from '@apollo/client';
const MUTATION = /* see mutation above */;

function UploadFile() {
  const [mutate] = useMutation(MUTATION);

  return (
    <input
      type="file"
      required
      onChange={({
        target: {
          validity,
          files: [file],
        },
      }) => {
        if (validity.valid)
          mutate({
            variables: {
              file,
            },
          });
      }}
    />
  );
}

I hope the code snippets above are self-explanatory (considering this is applicable to all frontend frameworks). If you run into any issues, always feel free to tag me in the comment section, and I'll respond as soon as I can!

Wrapping Up...

You should now have a working, end-to-end GraphQL file upload system, complete with server, DTOs, middleware, resolvers, upload streaming, Apollo Client, and a front-end implementation.
If there's a framework or storage backend I missed, or you have a better implementation, drop your thoughts in the comments!
Until next time, happy hacking!

From Basics to Best Practices: Why Angular Developers Should Adopt GraphQL

Fri, 20 Jun 2025 03:04:20 +0000

As Angular developers, we’re used to structured development, powerful CLI tools, and TypeScript's safety. But when it comes to APIs, most of us still work with REST. While REST has served us well, GraphQL offers a modern, more flexible alternative—especially when building dynamic, scalable Angular applications.

In this blog, we’ll explore why GraphQL fits naturally into Angular projects, how to get started, and what best practices to follow.

Why Should Angular Developers Care About GraphQL?

1. Strong Typing = TypeScript's Best Friend

GraphQL uses a strongly-typed schema, which integrates perfectly with Angular's TypeScript-first ecosystem. With tools like GraphQL Code Generator, you can auto-generate TypeScript types for your queries, reducing errors and boosting DX (developer experience).

2. Single Endpoint, Precise Queries

Instead of juggling multiple REST endpoints, GraphQL uses one endpoint and lets clients ask for exactly what they need. This avoids over-fetching/under-fetching and speeds up UI development in Angular components.

3. Better for Complex UIs

GraphQL’s nested queries let you fetch related data in one go—ideal for component-driven UIs in Angular, where you need parent and child data together.

Setting Up GraphQL in an Angular Project

Step 1: Install Apollo Client

Use Apollo Angular to integrate GraphQL easily.

ng add apollo-angular

If the CLI command doesn’t work, install manually:

npm install @apollo/client graphql apollo-angular

Step 2: Configure Apollo Client

// app.module.ts
import { NgModule } from '@angular/core';
import { HttpClientModule } from '@angular/common/http';
import { ApolloModule, APOLLO_OPTIONS } from 'apollo-angular';
import { HttpLink } from 'apollo-angular/http';
import { InMemoryCache } from '@apollo/client/core';

@NgModule({
  imports: [HttpClientModule, ApolloModule],
  providers: [
    {
      provide: APOLLO_OPTIONS,
      useFactory: (httpLink: HttpLink) => ({
        cache: new InMemoryCache(),
        link: httpLink.create({ uri: 'https://your-graphql-api.com/graphql' }),
      }),
      deps: [HttpLink],
    },
  ],
})
export class AppModule {}

Step 3: Create a Query in Your Component

// app.component.ts
import { Component } from '@angular/core';
import { Apollo, gql } from 'apollo-angular';

const GET_USERS = gql`
  query {
    users {
      id
      name
      email
    }
  }
`;

@Component({
  selector: 'app-root',
  template: `
    <h1>Users</h1>
    <ul *ngIf="users">
      <li *ngFor="let user of users">{{ user.name }} ({{ user.email }})</li>
    </ul>
  `,
})
export class AppComponent {
  users: any[] = [];

  constructor(private apollo: Apollo) {
    this.apollo.watchQuery({ query: GET_USERS }).valueChanges.subscribe((result: any) => {
      this.users = result?.data?.users || [];
    });
  }
}

Bonus: Auto-Generate Types

Install GraphQL Code Generator:

npm install @graphql-codegen/cli
npx graphql-codegen init

This tool reads your schema and queries, and auto-generates TypeScript interfaces, query functions, and hooks for Angular.

Best Practices for Angular + GraphQL

Practice	Why it matters
✅ Use GraphQL Codegen	Ensures strict type safety and DX
✅ Use Apollo Caching	Boosts performance with normalized caching
✅ Separate Queries/Mutations	Keep queries in `.graphql.ts` or `.gql` files
✅ Use Fragments	Reuse common fields between components
✅ Use Interceptors	Add auth tokens dynamically
✅ Paginate Large Lists	Avoid loading unnecessary data

Angular & GraphQL Auth Tip

To attach auth tokens to GraphQL requests, use an ApolloLink:

import { setContext } from '@apollo/client/link/context';

const authLink = setContext((_, { headers }) => {
  const token = localStorage.getItem('token');
  return {
    headers: {
      ...headers,
      Authorization: token ? `Bearer ${token}` : '',
    },
  };
});

Then combine authLink with httpLink using from:

link: from([authLink, httpLink.create({ uri: '...' })])

Summary: Why Angular Devs Should Adopt GraphQL

Benefit	Impact
Typed queries	TypeScript-friendly development
Declarative data loading	Cleaner, more readable components
Schema introspection	Better tooling and autocompletion
Single endpoint	Less REST boilerplate, more flexibility
Ecosystem support	Apollo, Codegen, DevTools, Angular CLI

Useful Resources

Ready to ditch the REST and supercharge your Angular app? GraphQL isn't just a trend—it's a robust tool for building modern, efficient frontends. And in Angular’s TypeScript-powered world, it's a perfect match.