How should we handle file uploads?

Part of the API that I'm working on allows for files to be uploaded. Is this something that the spec could / should / does already cover?

[steveklabnik]

I don't think there's anything that makes file uploads particularly special. If you can think of some reason why there's something missing, we can talk about it, but we'd need more specifics.

[Fivell]

@steveklabnik , media type should be different or not in this case?

[NuckChorris]

@steveklabnik What makes file uploads special?

Let's assume you have a profile with an avatar field. In the JSON API it's exposed as a URL in a text field. You ideally want a symmetry where the client can set that field to a binary blob and they'll get back the new URL. Some APIs (Stripe, for instance) use an out-of-band upload system, but this brings with it a whole slew of timing and cleanup issues, and removes the symmetry.

This means we basically have three options: we can either submit them as base64 in a JSON body (and eat the 25% overhead plus additional processing), you can submit them as multipart/form-data and ditch the whole JSON-API thing, or you can set them up as a sub-resource which can be edited by uploading to it, like PUT /users/17/avatar (which means you have to handle it separate from your standard download-modify-upload lifecycle)

I think this qualifies as complex enough and encourages bikeshedding in teams enough that JSON-API ought to tackle it, even if only in an extension.

[patrykorwat]

Note that 25% is only about the amount of sent data over the network. Current implementations of web servers (at least in Java) for multipart/form-data uses algorithms which just stream data using a single buffer (O(1) memory complexity), whereas in case of JSON files it is required to process whole file in memory (O(n) memory complexity).

[NuckChorris]

@meshuga The 25% is for base64 embedded in JSON, not multipart. Multipart should send it over the wire as plain binary I believe, with just the added overhead of the headers and dividers

You're absolutely right that Multipart is O(1) memory and data: is O(n), and this just goes to prove my point: file uploads are friggin confusing and should be within the scope of JSONAPI or an extension

[johnnncodes]

+1. Would be great if jsonapi spec would cover this.

[ersinakinci]

+1.

[gponsu]

+1

[saneshark]

+1

[shannontan-addepar]

+1

[wendelin]

+1