Course contentsShow
← Web Development
Lesson 1553 of 2,98228. GraphQL FundamentalsFree lesson

File Uploads: REST Multipart vs GraphQL Approaches

How file uploads work differently in REST versus GraphQL's mutation-based or specialized approaches.

File Uploads: REST Multipart vs GraphQL Approaches

You'll learn how file uploads work differently in REST versus GraphQL, and why GraphQL requires special handling for binary data.

Why File Uploads Are Different

File uploads involve sending binary data (images, documents, videos) from client to server. REST and GraphQL handle this challenge in fundamentally different ways due to their underlying protocols.

REST's Native Multipart Approach

REST uses HTTP's built-in multipart/form-data content type. You can directly POST a file to a resource endpoint:

POST /api/users/123/avatar
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary

------WebKitFormBoundary
Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: image/jpeg

[binary data here]
------WebKitFormBoundary--

This works seamlessly because REST embraces HTTP's full feature set. The server receives the file in the request body, processes it, and returns a response—straightforward and well-supported by all HTTP clients.

GraphQL's Challenge

GraphQL operations typically send JSON in the request body. JSON cannot natively represent binary data. Since GraphQL queries and mutations expect structured data, not raw files, you face a mismatch.

Two main approaches emerged:

  1. Separate REST endpoint: Use GraphQL for data operations but keep a traditional REST endpoint (POST /upload) for files. After upload, the REST endpoint returns a URL that you pass to a GraphQL mutation.

  2. GraphQL Multipart Request Specification: A community standard that maps file uploads to GraphQL variables using the same multipart/form-data format REST uses, but with additional JSON mapping instructions.

The Trade-off

REST's approach is simpler and more universally supported. GraphQL's specialized solutions add complexity but maintain the single-endpoint philosophy. Many teams pragmatically mix both: GraphQL for data queries and mutations, REST for file handling.

Key Takeaway: REST natively supports file uploads through HTTP multipart requests, while GraphQL requires either separate REST endpoints or specialized multipart specifications to handle binary data outside its JSON-based protocol.