1 Requesting Completion
2 Ordering the Parts
3 Response Headers for Multipart Writes
- 3.1 Initiation Response
- 3.2 Completion Response

The multipart write procedure is completed using a POST request with the ?uploadId=<uploadid> query argument and no ?partNumber. Include a list of all individual parts in JSON format with the Content-UUID and part numbers recorded for each object when the parts are uploaded in the body of the request. The completion request fails if multiple parts with the same part number are accidentally included.

Swarm creates the new object or modifies the existing object by assembling the uploaded parts in ascending part-number order (the default) or by the manifest order when the multipart write is completed. An existing object is modified as specified in the initiate request, either overwriting all data with a PUT or adding the multipart upload data with an APPEND.

Changes During the Write

The following operations occur when an existing object is the target of a multipart write and changes to that object occur before the write completes:

PUT - the completion operation fails.
APPEND - the operation appends to the content as it exists upon completion, not as it existed when it was started.

Requesting Completion

The completion request must not include an encoding query argument, as it inherits whatever was specified on the initiate request. Custom metadata may be provided with the complete request and is merged with the metadata provided in the initiate request. The metadata from the initiate request takes precedence if the metadata in the two requests collide.

Parallel Upload Complete Request for 3-Part Object

POST /exampleBucket/ObjectName?uploadId=UploadId HTTP/1.1 

{
   "parts": [
      {
         "partNumber": 1,
         "uuid": "12345678901234567890123456789012"
      },
      {
         "partNumber": 2,
         "uuid": "12345678901234567890123456789013"
      },
      {
         "partNumber": 3,
         "uuid": "12345678901234567890123456789014"
      }
   ]
}

Important

Verify the part numbers and corresponding Content-UUIDs of all required parts are included in the manifest before the request is completed. Any part not included with the manifest is not used in the final object and is eventually be deleted by the Health Processor.

Ordering the Parts

Parts are ordered by part number by default. Use the global value sortOrder set to natural (which is the manifest order) if the parts need to be reassembled according to the order they appear in the manifest rather than by the part number.

Parallel Upload Complete Request with Manifest Order

POST /exampleBucket/ObjectName?uploadId=UploadId HTTP/1.1 

{
   "sortOrder" : "natural",   
   "parts": [
         "partNumber": 2,
         "uuid": "12345678901234567890123456789013"
      },
      {
         "partNumber": 3,
         "uuid": "12345678901234567890123456789014"
      }
      {
         "partNumber": 1,
         "uuid": "12345678901234567890123456789012"
      },
      {
 ]
}

Response Headers for Multipart Writes

Swarm uses chunked transfer encoding to verify the client socket remains open throughout a lengthy complete for multipart write operations. Chunked transfer encoding is the streaming data transfer mechanism in HTTP/1.1. The chunking method allows content to be transferred iteratively along with the information needed to verify when it has been received in full. The method is specified by this response header: Transfer-Encoding: chunked

The data is divided into non-overlapping "chunks" sent and received independently in chunked encoding. The encoding modifies the message body to transfer it as a series of chunks, each of which is preceded by a size indicator (in bytes). The transmission ends when a 0-length chunk is received, which can be followed by a trailer that's terminated by an empty line. Swarm uses the trailer to send additional HTTP header fields with information about the multipart operation completion.

Initiation Response

These are the typical results and relevant headers for the initiation of the multipart operation:

`Castor-System-Result`	Additional Headers	Notes

Additional Headers

Notes

400 (Bad Request)
404 (Not Found)
...

The result indicates warm found an error before starting the completion process, such as a problem with the parts manifest.

See https://perifery.atlassian.net/wiki/spaces/public/pages/2443821260.

202 (Accepted)

The result indicates Swarm has accepted the uploaded parts and begins assembling them into a new object.

The initial response includes a Completion-Etag with the value of the expected ETag for S3 compatibility. There is no new object and this ETag provided is not valid if there is an error later. (v11.1)

Completion Response

These are the typical results and relevant headers for the completion of the multipart operation:

	Additional Headers	Notes