Polish upload API

The batch upload REST API has been improved to allow:

• Batch initialization.
• File upload in chunks.
• Getting information about the chunks uploaded for a given file.
• Resumable upload.

Resumable upload became a requirement otherwise uploading large files over a broken connection could take days.
Using chunking is a good idea since:

• It allows to manage upload resume with enough granularity (restart with chunk x).
• It allows multiplexing (upload on multiple TCP streams)
• It allows to overcome the limitations of some reverse proxies (limits the risk of having a POST considered as too big).

This is mainly a server-side feature, but ultimately it will be used by:

• Nuxeo Drive, see NXDRIVE-433
• Drag and drop and Bulk import, see NXP-18031
• JS client, see NXJS-29

As a reminder, here is the old batch upload API that has been deprecated but kept for backward compatibility.

Old API, deprecated

Upload a file

POST /site/automation/batch/upload
 
X-Batch-Id client-side generated uid
X-File-Idx file index
X-File-Name file name
X-File-Size file size
X-File-Type mime type

Body contains the plain stream.
If the body is multipart encoded, batch id and file index are read from the form data.

Returns a 200 OK status code with the following JSON data:

{"batchId": batchId, "uploaded": "true"}

Get batch info

GET /site/automation/batch/upload/files/{batchId}

Returns a 200 OK status code with the following JSON data:

[{"name": xxx, "size": yyy}, {...}, ...]

Drop a batch

GET /site/automation/batch/upload/drop/{batchId}    

Returns a 200 OK status code with the following JSON data:

{"batchId": batchId, "dropped": "true"}

New API

Initialize a batch

POST /api/v1/upload/

Returns a 201 CREATED status code with the following JSON data.

{"batchId": batchId}

This handshake phase is mandatory to acquire a server-side generated batch id to be used in subsequent requests.
The batch id can be seens as an upload session id, especially for a resumable upload.

Upload a file or a chunk with an order number

POST /api/v1/upload/{batchId}/{fileIdx}

X-Upload-Type "chunked" / "normal"
Content-Length file or chunk length
X-Upload-Chunk-Index chunk index
X-Upload-Chunk-Count total chunk count
X-File-Name file name
X-File-Size file size
X-File-Type file mime type

Here again the body contains the plain stream and we support multipart encoded upload.
The batchId must match an existing batch initialized by a call to the previous POST request, otherwise you will get a 404 Not Found status code.

Returns a 201 Created status code for a whole file or a complete chunked file and a 308 Resume Incomplete status code for an incomplete chunked file.
JSON response data:

{"batchId": batchId, "fileIdx": fileIdx, "uploadType": "normal"/"chunked", "uploadedSize": xxx [, "uploadedChunkId": x, "chunkCount": y]}

Get batch Info

GET /api/v1/upload/{batchId}

Returns a 200 OK status code if the batch contains at least one file and a 204 No Content status code if the batch doesn't contain any file.
JSON response data:

[{"name": xxx, "size": yyy, "uploadType": "normal"/"chunked" [, "uploadedChunkIds": [0, 1, 2, 4, ...], "chunkCount": 10]}]

Get file info

GET /api/v1/upload/{batchId}/{fileIdx}

Returns a 200 OK status code for a whole file or a complete chunked file and a 308 Resume Incomplete status code for an incomplete chunked file.
If the batch doesn't contain any file with the given index, returns a 404 Not Found status code.
JSON response data:

{"name": xxx, "size": yyy, "uploadType": "normal"/"chunked" [, "uploadedChunkIds": [0, 1, 2, 4, ...], "chunkCount": 10]}

Drop a batch

DELETE /api/v1/upload/{batchId}    

Returns a 200 OK status code with the following JSON data:

{"batchId": batchId, "dropped": "true"}