jaydenseric
commented
6 years ago Thanks for the question, it is fair to say it's pretty hard to get up to speed with the state of the art of file uploads over GraphQL. The evolution of this spec and it's implementations, while not complete, is the result of a lot of iteration. I will try to quickly do the question justice, but really there is a lot of work to go to take the latest implementations out of alpha and PR official Apollo packages, improve documentation and write a big blog post.
TL;DR this spec is:
- Arguably the most flexible and intuitive approach.
- Used in production by companies such as Xero and Grapple.
- Openly documented and versioned for multiple client/server implementations.
- Being integrated into official Apollo packages.
Upload via mutations or queries
You can use files in query arguments; requests do not have to be mutations. Perhaps useful for APIs such as search by image.
Nest files anywhere in query variables
File instances are magically handled wherever they are found and can be nested anywhere; even in arrays mixed in with other types. Other approaches require specially named variables that contain all the files, or can only handle top level file variables. No one has thought of a good use case yet, but technically the spec allows placement of files anywhere in request objects; not just the variables.
Batching
Batching is supported, but optional. Either way works with similar implementation logic.
File deduplication
A file can be uploaded only once if it is used in multiple places in the query variables, or even if it occurs within multiple batched requests. The spec allows for this, although it is really up to client implementations to take advantage. I have not yet prioritized testing this in mine.
File upload streams in resolvers
This spec and it's implementations are uniquely built from the ground up for uploads to be non-blocking to resolvers. See jaydenseric/apollo-upload-server#13 to learn more about what this is, and why it's awesome.
I just made a quick graphic for you to help explain:
Apollo integrations
After multiple in-person and video conference discussions with the Apollo team and other contributors, it has been decided to adopt this spec for apollo-link-http, as an opt-in feature. There have also been discussions with the Apollo Engine team to support multipart requests. The plan is to allow this spec to work unencumbered, but special tracking in Engine is not a high priority.
It's easier for me to answer specific questions about spec or implementation design decisions, or pros/cons to specific aspects of other approaches.
PowerKiKi
In a discussion about whether to implement this spec or something else, it came up that express-graphql, apollo-server-express and relay seems to all do something similar, which seems to be different than
graphql-multipart-request-specis doing.Could you explain why you did differently ? Whether you were aware of those pseudo-standard ? And in what way
graphql-multipart-request-specis better ? or the limitations of the "express way" ?I feel the answers to those question could be part of the spec itself, as an introduction or meta document. It would certainly help to promote this spec.