Introducing the Chunked Uploads API
Uploading large files to the cloud can be difficult and frustrating. Spotty or weak HTTP connections mean uploads can take far too long to complete. Or worse, your requests time out and leave users with no choice but to start the entire upload over again.
That’s why today, we are introducing a new API in the Box Platform called the Chunked Upload API. The Chunked Upload API provides a fast and reliable way to upload large files to Box by chunking them into a sequence of parts, which can be uploaded in parallel. Moreover, if any part of the file fails to upload, you’ll only need to retry upload for that single part, as opposed to the entire file.
To learn more about the Chunked Upload API, please visit our developer documentation. The Chunked Upload API is only for uploading large files and will not accept files smaller than 20MB in size.
To make your life easier, we also updated a few of our top SDKs to include methods to automatically handle a chunked upload.
We have also added the Chunked Upload API to the Box OpenAPI specification. You can check that out on Github here.
How do chunked uploads work?
Using the Chunked Upload API is simple: using the API, you create an upload session, upload chunks of the file to that session, and then commit the session to create the assembled file in Box.
Create an upload session
An upload session is a temporary space where your large file will eventually live. To create an upload session, make a POST request that includes the folder where you want the file to live, the overall size of the file, and the name for the large file. Here’s an example where we upload a 100MB file to our root folder (where the folder_id is 0) and name it “Chunked Upload Example.”
curl -X POST \https://upload.box.com/api/2.0/files/upload_sessions \-H ‘authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc \-d ‘{“folder_id”: “0”,“file_size”: 1000000000,“file_name”: “Chunked Upload Example”}’
The API will return a 201 created, along with a list of endpoints for that upload session that include the session_id. These endpoints include list_parts, commit, upload_part, status, and abort.
Upload parts to your upload session
Using the upload_part endpoint in the response from the previous step, we can then start to upload parts of the file to our upload session. To upload a part, you’ll need the session_id and you’ll need to make individual PUT requests for each part.
# Part 1: curl -X PUT \ https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD \-H ‘authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc’ \-H ‘content-range: bytes 0–8388607/100000000’ \-H ‘content-type: application/octet-stream’ \-H ‘digest: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=’ \ — data-binary @/tmp/part1# Part 2: curl -X PUT \ https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD \-H ‘authorization: Bearer fEw9FPUVT3SJGaSBu4Q07VFyqdYd3ODc’ \-H ‘content-range: bytes 8388608–9999999/100000000’ \-H ‘content-type: application/octet-stream’ \-H ‘digest: sha=Oj0SVJEpmxvBarOzs9hkUuPIoOM=’ \ — data-binary @/tmp/part2
Upon upload, the API will return a 200 response with the part_id for each part.
Commit upload
Last, you’ll commit your upload session and upload all the parts to Box. Once uploaded, Box will assemble the parts into a single file, which can then be interacted with using any normal file API. To construct your POST request, you’ll need the session_id and an array of parts including the part_ids in that session. You can also set any attributes that you want to appear on the created file.
curl -X POST \https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit \-H ‘authorization: Bearer spSSvCEepjG4PX3fO5IkcZe5h1nQYXfn’ \-H ‘content-type: application/json’ \-H ‘digest: sha=DhIcpd61HctMIGTMu7tyY54Da2U=’ \-d ‘{“parts”:[{“part_id”: “BFDF5379”,”offset”: 0,”size”: 8388608,”sha1": “7e94728397954257ad759a8429a165ab00572733”},{“part_id”: “E8A3ED8E”,”offset”: 8388608,”size”: 1611392,”sha1": “3a3d125491299b1bc16ab3b3b3d86452e3c8a0e3”}],“attributes”:{“content_modified_at”:”2017–04–08T00:58:08Z”}}’
Once you commit the upload, the API will return a response similar to that of the file upload API response, where you will receive a 201 created response that includes your file_id.
You can dive deep into this new API in our developer documentation. If you have any questions about using the Chunked Uploads API or anything else, feel free to post in the Box Developer Forum or reach out to us on Twitter. If you don’t have a Box Developer account, you can create one here.
We can’t wait to see what you build!
