Uploaded image for project: 'Nuxeo Platform'
  1. Nuxeo Platform
  2. NXP-16953

Polish upload API

    XMLWordPrintable

    Details

    • Type: New Feature
    • Status: Resolved
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 7.4
    • Component/s: File Upload , Rest API
    • Impact type:
      API change
    • Upgrade notes:
      Hide

      Deprecated:

      @POST
      @Path("/upload")
      BatchResource#doPost(@Context HttpServletRequest request)

      @GET
      @Path("/files/

      {batchId}")
      BatchResource#getFilesBatch(@PathParam(REQUEST_BATCH_ID) String batchId)

      @GET
      @Path("/drop/{batchId}

      ")
      BatchResource#dropBatch(@PathParam(REQUEST_BATCH_ID) String batchId)

      Added BatchUploadObject

      Show
      Deprecated: @POST @Path("/upload") BatchResource#doPost(@Context HttpServletRequest request) @GET @Path("/files/ {batchId}") BatchResource#getFilesBatch(@PathParam(REQUEST_BATCH_ID) String batchId) @GET @Path("/drop/{batchId} ") BatchResource#dropBatch(@PathParam(REQUEST_BATCH_ID) String batchId) Added BatchUploadObject
    • Sprint:
      Drive, drive-7.4
    • Story Points:
      8

      Description

      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:

      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"}
      

        Attachments

          Issue Links

            Activity

              People

              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  PagerDuty

                  Error rendering 'com.pagerduty.jira-server-plugin:PagerDuty'. Please contact your Jira administrators.