For very small files, you can encode binary data into a Base64 string and include it as a field in your JSON response. However, this increases the file size by approximately 33% and can cause memory issues for larger files.
Instead of serving the file directly, your GraphQL server generates a temporary, securely signed URL (from services like AWS S3 or Google Cloud Storage) and returns it in the query response. The client then downloads the file directly from the storage provider, offloading the heavy lifting from the API server. graphql download
Many teams use GraphQL for metadata (filenames, sizes, permissions) but keep a dedicated REST endpoint for the actual binary download. This allows you to use standard browser features like Content-Disposition for native "Save As" prompts. Comparing Download Techniques Signed URLs Base64 Encoding REST Endpoint Best For Large files & high traffic Icons/Small thumbnails Legacy integration Performance High (offloaded) Low (overhead) Browser Support Manual decoding required Complexity Medium (S3 config) Low (coding) Medium (dual APIs) Implementation Considerations Handling File Uploads in GraphQL For very small files, you can encode binary
While GraphQL was designed primarily for structured data exchange, downloading files or large datasets is a frequent requirement in modern applications. Because GraphQL uses a JSON-based transport, handling binary data like PDFs or CSVs requires specific strategies to maintain performance and scalability. Core Strategies for GraphQL Downloads The client then downloads the file directly from
Since GraphQL cannot natively stream binary file data in a JSON payload, developers typically use one of three main patterns: