About File Upload

About File Upload

Contents

Introduction

Verizon Personal Cloud Storage APIs provide your app access to the most comprehensive set of data classes: contacts, photos, videos, music, documents, call logs, MMS and SMS (subject to the user’s prior approval). They also allow users to access and manage their contents on any of their devices, even when they are on-the-go.

While uploading files which are only a few hundred of kilobytes in size on a standard connection typically does not pose any difficulties, this often might not be the case for your users. Your app should be able to upload large files, such as videos efficiently. It should also be able to recover from interrupted uploads that might be caused by mobile connectivity issues or power outages, without having to restart the upload process.

Chunked file uploads allow you to break a large file into small chunks, and then send these pieces to the upload server one-by-one. If an upload were to fail, your app would not have to resend the whole file. It can resume the file upload from the last successfully sent chunk.

NOTE: You cannot perform the file upload operation on a virtual folder.

Basic Steps

File upload using the Verizon Personal Cloud Storage APIs consists of the following basic steps:

  1. File upload intent

    File upload intent request is initiated by a call to GET /fileupload/intent API.

  2. File upload

    Depending on the size of the file, the upload can be chunked or non-chunked.

    • non-chunked file upload requires a single POST /upload API call.
    • chunked file upload requires multiple POST /upload API calls.
  3. Completion of chunked file upload

    After all file chunks have been successfully uploaded, call POST /commit API to complete the file upload. All chunks are re-assembled on the server to form the original file.

NOTE: When uploading files, note the following limitations:

  • The maximum chunk size is 100 MB.

Detailed Description

1. File Upload Intent

A call to GET /fileupload/intent is the first step required to upload a file. The file upload can be either chunked or non-chunked.

Non-Chunked File Upload Intent

  1. Include Authorization header.
  2. Specify the required query parameters:

    • checksum - SHA256 checksum of the file/chunk. checksum must be lower case.
    • name - the name of the file to be uploaded.
    • path - the full path to the folder where the file is to be uploaded.
    • size - the size of the file to be uploaded.
  3. Set the chunk parameter to “false”, as in this example:

        "https://api.cloudapi.verizon.com/cloud/1/fileupload/intent?chunk=false"
    
  4. Successful response will look like this and include uploadurl and uploadid (a unique upload id specific to your upload request):

    {
        "uploadurls":{
          "uploadurl":"https://api.cloudapi.verizon.com/cloud/1/upload/<uploadid>?chunk=false"
        }
    } 
    

Chunked File Upload Intent

  1. Include Authorization header.
  2. Specify the required query parameters:

    • checksum - SHA256 checksum of the file/chunk. checksum must be lower case.
    • name - the name of the file to be uploaded
    • path - the full path to the folder where the file is to be uploaded
    • size - the size of the file to be uploaded
  3. Set the chunk parameter to “true”, as in this example:

    "https://api.cloudapi.verizon.com/cloud/1/fileupload/intent?chunk=true"
    
  4. Successful response includes:

    • uploadurl and uploadid (a unique upload id specific to your upload request)
    • commiturl and uploadid (a unique upload id specific to your upload request)
    {
    "uploadurls": {
        "uploadurl":"https://api.cloudapi.verizon.com/cloud/1/upload/<uploadid>?chunk=true",
        "commiturl":"https://api.cloudapi.verizon.com/cloud/1/commit/<uploadid>"
    }
    }
    
    

NOTE: The maximum chunk size is 100 MB.

2. File Upload

A call to POST /upload is the second step required to upload a file.

Non-Chunked File Upload

Non-chunked file upload requires a single POST /upload request against the upload URL.

  1. Include Authorization header.
  2. Specify uploadid path parameter - obtained via a call to the GET /fileupload/intent and embedded in the URLs included in the response.
  3. Specify the required query parameter:

    • checksum - SHA256 checksum of the file/chunk. checksum must be lower case.
  4. Set the chunk parameter to false.

    EXAMPLE:

    curl -X “POST” -H "Authorization: Bearer <access_token>”  -H "Content-Type: application/octet-stream"  "https://api.cloudapi.verizon.com:443/cloud/1/upload/<uploadid>?chunk=false&checksum=<checksum_value>”  —data-binary @<filename>
    

    NOTE: For the non-chunked file upload, the maximum file size is 100 MB.

Chunked File Upload

For chunked file uploads, each chunk is sent as a separate POST /upload API call.

In each request, use the uploadurl returned from GET /fileupload/intent multiple times, once for each chunk. Append the chunk number using the offset query parameter for each call.

  1. Include Authorization header.
  2. Specify uploadid path parameter - obtained via a call to the GET /fileupload/intent and embedded in the URLs included in the response.
  3. Specify the required query parameters:

    • checksum - SHA256 checksum of the file/chunk. checksum must be lower case.
    • offset - the sequence of the upload in chunk data
  4. Set the chunk parameter to true.

EXAMPLE:

The following is an example of a chunked file upload with two chunks:

  1. Upload the first chunk.

    curl -X POST -H "Authorization: Bearer <access-token>" -H "Content-Transfer-Encoding: binary" -H "Content-Type: application/octet-stream" "https://api.cloudapi.verizon.com/cloud/1/upload/<uploadid>?chunk=true&offset=1" --data-binary @<chunk1-file>
    
  2. Upload the Second chunk.

    curl -X POST -H "Authorization: Bearer <access-token>" -H "Content-Transfer-Encoding: binary" -H "Content-Type: application/octet-stream" "https://api.cloudapi.verizon.com/cloud/1/upload/<uploadid>?chunk=true&offset=2" --data-binary @<chunk2-file>
    
  3. Repeat for as many chunks as required.

3. Completion of Chunked File Upload

Once all chunks are uploaded successfully, indicate that the file upload is complete by issuing a call to the POST /commit API to complete the file upload. All chunks are re-assembled on the server to form the original file.

EXAMPLE:

curl -X POST -H "Authorization: Bearer <access-token>" "https://api.cloudapi.verizon.com/cloud/1/commit/<uploadid>"

Copyright © 2015-2017, Verizon and/or its Licensors. All rights reserved.