Working with file uploads using Altair GraphQL

May 06, 2020

It’s no news that GraphQL is still the new kid on the block and has come to stay (don’t worry REST APIs still have their place 😄). As the GraphQL community grows and the specification is developed, there remains a few questions yet to be answered. One of such questions was about file uploads.

How do we upload files using GraphQL?

Are there any guidelines for uploading files using GraphQL?

Well there isn’t one from the GraphQL team yet. So it is still left to you to define how you would want to handle file (binary data) uploads. You could always encode the data as base64 and pass the encoded string along to the server. You could also upload the files to a cloud storage service (or any other storage service) from the client and just pass the URL returned from the storage service through a GraphQL mutation. Whichever option you choose, it’s not ideal to work that way, especially considering that traditional methods of posting data to the server (submitting a form, sending a form data to an API) are more efficient in handling file uploads. So why would GraphQL be less efficient?

I can only assume, but I guess that was the question Jayden had in mind when he created the GraphQL multipart request specification. From the spec readme, the specification is:

An interoperable multipart form field structure for GraphQL requests, used by various file upload client/server implementations.

It’s possible to implement:

Nesting files anywhere within operations (usually in variables).

Operation batching.

File deduplication.

File upload streams in resolvers.

Aborting file uploads in resolvers.

TL;DR, the specification enables you to upload files using the multipart format, which was designed for sending binary data through HTTP from the client to the server. There are several library implementations of this GraphQL spec already in Node.js, PHP, Python, Go and Ruby, so should be easy to implement without having to create it from scratch. Altair GraphQL Client (from v2.0.5) now allows you to upload files to your server if you have implemented the GraphQL multipart request spec in your server. It supports uploading both single files and an array of files (using the dot notation e.g. for an array named fileList, you define the files as fileList.0, fileList.1, fileList.2 and so on).

Adding file for upload (single file)

Adding files for upload (list of files)

You add your files in the variables pane, and the files are added to the request as variables when the request is sent to the server.

Note: The files don’t persist if you reload Altair, so you would have to select them again.

Feedback

Do you like this feature? Do you think it can be improved? Did you find a bug? Let me know what you think. Create an issue on Github or add a comment to this issue.

Did you find this useful? Do you think there are better approaches to take, or questions? You can reach out to me on twitter @imolorhe.

Write about what you learn. It pushes you to understand topics better.
Sometimes the gaps in your knowledge only become clear when you try explaining things to others. It's OK if no one reads what you write. You get a lot out of just doing it for you.
@addyosmani