Uploads and downloads

Uploads put a file’s bytes into the Drive, and downloads and exports read them back; all of it runs on one port, /upload/drive/v3 for the uploads and /drive/v3 for the rest.

Start a resumable upload, send it in two chunks and read the finished file. Every chunk but the last must be a multiple of 262144 bytes:

AUTH='Authorization: Bearer ya29.placeholder'
LOC=$(curl -si -H "$AUTH" -H 'Content-Type: application/json' -H 'X-Upload-Content-Type: application/octet-stream' -d '{"name":"big.bin"}' "$RYSTIC_URL/upload/drive/v3/files?uploadType=resumable" | awk -F': ' 'tolower($1)=="location"{print $2}' | tr -d '\r')
head -c 262144 /dev/zero | curl -si -X PUT -H "$AUTH" -H 'Content-Range: bytes 0-262143/262149' --data-binary @- "$LOC" | grep -i '^range'
# -> Range: bytes=0-262143
ID=$(printf 'abcde' | curl -s -X PUT -H "$AUTH" -H 'Content-Range: bytes 262144-262148/262149' --data-binary @- "$LOC" | jq -r .id)
curl -s -H "$AUTH" "$RYSTIC_URL/drive/v3/files/$ID?fields=name,size" | jq -c .
# -> {"name":"big.bin","size":"262149"}

Upload types

uploadType=media sends the bytes alone and uploadType=multipart sends metadata and bytes together. Both create a file on POST and replace one on PATCH of /upload/drive/v3/files/{fileId}. A media upload onto a folder answers 200 and leaves the folder unchanged. Both official libraries send multipart by default and switch to resumable for a large file.

A resumable upload is served as Drive serves it: the initiate answers a Location session URI on the simulator, each chunk answers 308 with a Range header, and the last chunk answers the file. A chunk that is too small, or whose length disagrees with its Content-Range, answers 400.

An upload holds at most 64 MiB: a request body over it, a multipart body’s metadata and part headers included, answers 413 request body exceeds blob_cap_bytes 67108864, where Drive takes up to 5,120 GB.

Downloads

alt=media on files.get or on a revision returns the file’s bytes. A Range header answers 206 with that range, and one past the end answers 416 with Drive’s JSON error. A file you upload or copy downloads byte for byte, and a shipped scenario’s binary files download small real payloads that match their size and checksums.

Exports and download operations

files.export converts a Google Docs Editors file, a document, sheet or slide deck, to a type you name with mimeType. An export is a stand-in built from the file’s name and description, never a rendering of its content.

files.download starts a download operation for a file, never a folder, and answers an operation that is already done; operations.get reads it back for the user who started it. For a binary file the operation’s downloadUri fetches its bytes from the simulator. For a Google Docs Editors file it names a Google host that the simulator never serves, so do not fetch it.