File Uploads on GraphQL: Why or Why not

Note: The code mentioned in this post can be found in these repositories.

NestJS Reference — @mrsauravsahu/blog-graphql-nestjs-fileupload

.NET Reference — @mrsauravsahu/blog-graphql-dotnet-fileupload

Moon (Made with Blender)
The Moon (Moon — Apollo — GraphQL, “get it? 😂”), made with Blender [@photosbysaurav on Instagram]

GraphQL has become quite popular due to its various features fixing under/over fetching issues. It also allows for easy caching, federation, non-versioning APIs, subscriptions etc,.

For the modern Internet where data needs to be accessible on various types of applications running on various types of devices, GraphQL seems like a great way forward and also a good concept to put into your knowledge bag.

GraphQL request and responses are typically in JSON format even though the GraphQL Spec doesn’t mandate any format.

All data fetching and uploading can be done easily with GraphQL and responses can also use GZIP for compression.

One thing GraphQL lacks (or rather doesn’t have a standard implementation for) is File Uploads.

There’s no right or wrong here, but here are a few things to consider when you want to have file uploads and you also have a GraphQL API.

Standardization: Because typically GraphQL APIs use JSON format, they don’t require Content Negotiation. This means that File Uploads, which use a multipart format, can be tricky to standardize. Most GraphQL implementations do provide provisions to implement File Uploads through your GraphQL API however.

Fully-Featured: All GraphQL APIs will use a text-based response format, so file downloads will still require a separate endpoint. This means your file upload and download will become separated. Decide based on whether you’re fine with this or not.

All ingress at one-point: A good reason why you might want to use File Uploads through GraphQL is because you can still make sure all incoming data into your system is through the same endpoint. Not a strong argument, but traffic management does become easier.

Few ways to go about it —

1. Files as strings

If your APIs deal with very small files, you can get away with a simple conversion from the binary representation of your file to a base64 string.

Let’s see a simple example. If your file has the following content.

You can use an inputfield to get the file in the Frontend and read its contents (with a FileReader perhaps) and then create a base64 string with the window.btoaWebAPI.

From now, your file can be treated as a base64 string so processing it is fairly similar to how you process regular strings in your application.

Note: As file sizes grow, your application needs to be able to handle larger strings as payload and response sizes will drastically increase.

This would mean that your files can be uploaded to a separate REST endpoint, either hand-written or something like a pre-signed URL upload to a Storage Account on Microsoft Azure/S3 on Amazon Web Services.

Finally! As mentioned earlier, some GraphQL implementations do allow uploading files with a multipart/form-data request format.

Let’s now see how this can be done with a NestJS GraphQL Server and a .NET GraphQL Server (with HotChocolate)

For NestJS, the GraphQL setup is fairly simple, read more about it here —

This uses the Apollo GraphQL Server, which does have support for File Uploads albeit through a different package.

So let’s install this package. This is the graphql-upload package, and because we’re using TypeScript, it’s good to also install the typings for it.

NestJS uses TypeGraphQL behind the scenes, which means our GraphQL Schema can be generated from TypeScript classes. I have a basic Model here.

This is a basic model to store details about a user, or a person rather.

For our File Upload to work, we need to initialize the graphql-uploadpackage in our main.ts

Let’s add a mutation which allows the consumer of our GraphQL API to upload a file and we’ll return the length of the file in bytes.

Here, the GraphQLUploadtype creates a scalar in our GraphQL Schema which allows for uploading. As you can see, we get the stream in our handler and we can do any type of processing on it.

We’re putting the chunks of the multipart upload together and then writing to a file, but you can also pipe the readStream to a file directly. This is just to show that you can handle the raw bytes in your file.

However, this code looks a bit unwieldy due to the stream events, so thanks to a newer node feature, we can use a for await loop instead.

We can replace the stream.on calls with this -

This is pretty neat, isn’t it.
So, that’s how you can implement File Uploads on your GraphQL API with NestJS.

HotChocolate, one of the most popular GraphQL libraries for .NET also has an implementation for File Uploads.

At the time of writing, I was on an RC version of .NET 6. But this works for .NET 6.0.100 as well. Yay! this means there’s really less code.

This is my Program.cs

As you can see I’m setting up GraphQL with Services. To allow file uploads, I have to add the Upload Scalar to my GraphQL Schema. This is done with the builder.Services.AddType<UploadType>()all.

Now we can write a similar mutation to handle our File Upload, which is the Mutation class I have registered in this case.

HotChocolate gives you an IFile interface to work with, and you can get the stream from there. Now you have the power to process it however it makes sense for your application.

At the time of writing, Apollo Playground doesn’t support File Uploads through its UI. So you’re going to have to use Postman to test out your File upload

Shoutout to this answer on Stack Overflow — helped a lot —

You can also use the same thing with a curl command

Here, the map property maps our file and passes it on to our handler. You should also be able to get the mime-type and add more logic for those.

So, this was how you can do File Uploads with GraphQL, and also a few thoughts on if you really should? You can find the full code base in the links at the top.

Have a great one!

— Saurav, @mrsauravsahu everywhere.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Saurav Sahu

Opinions are my own. Full Stack Engineer. CEO of “it was just working 🤷‍♂️”