JSON API: Options for uploading objects

This page describes ways you can use the JSON API to upload objects to Cloud Storage. Any MIME type of data is permitted, and files may be up to 5 TB in size.

See Uploading objects for a quick guide to simple uploads using tools such as the JSON API.

You can send upload requests to the JSON API in any of the following ways:

• Simple upload: uploadType=media. Use this if both of the following apply:
  • The file is small enough to upload again in its entirety if the connection fails.
  • There is no object metadata to send as part of the request. To perform a simple upload, refer to the JSON API tab in the Uploading objects guide.
• Multipart upload: uploadType=multipart. Use this if both of the following apply:
  • The file is small enough to upload again in its entirety if the connection fails.
  • You want to include object metadata as part of the request. To perform a multipart upload, refer to Performing a multipart upload.
• Resumable upload: uploadType=resumable. Use this for more reliable transfer, which is especially important with large files. Resumable uploads are a good choice for most applications, since they also work for small files at the cost of one additional HTTP request per upload. To perform a resumable upload, refer to Performing a resumable upload.

All of these options require you to include an OAuth 2.0 token in your request. See Authorize requests for details about obtaining OAuth tokens.

Upload size considerations

When choosing whether to use resumable uploads instead of simple or multipart uploads, consider the amount of time that you're willing to lose should a network failure occur and you need to restart the upload from the beginning. For faster connections, your cutoff size can typically be larger.

For example, say you're willing to tolerate 30 seconds of lost time:

• If you upload from a local system with an average upload speed of 8 Mbps, you can use simple or multipart uploads for files as large as 30 MB.

• If you upload from an in-region service that averages 500 Mbps for its upload speed, the cutoff size for files is almost 2 GB.