Performing a Simple Upload

This page provides details for performing a simple upload request in the Google Cloud Storage JSON API. See Uploading an object for a quick guide to simple uploads using tools such as the JSON API.

A simple upload is the most straightforward method for uploading a file. Use this option if:

  • The file is small enough to upload again in its entirety if the connection fails.
  • There is no metadata to send. This might be true if you plan to send metadata for the file in a separate request, or if no metadata is available.

If you need to provide metadata for the file, you can use multipart upload or resumable upload instead. For larger files (more than 5 MB) or less reliable network connections, use resumable upload.

Learn about request URIs

When you upload media, you use a special URI. In fact, methods that support media uploads have two URI endpoints:

  • The /upload URI, for the media. The format of the /upload endpoint is the standard resource URI with an /upload prefix. Use this URI when transferring the media data itself.

    For example, for a bucket named myBucket:

    POST /upload/storage/v1/b/myBucket/o

  • The standard resource URI, for the metadata. If the resource contains any data fields, those fields are used to store metadata describing the uploaded file. You can use this URI when creating or updating metadata values.

    For example, for a bucket named myBucket:

    POST /storage/v1/b/myBucket/o

Sending a simple upload request

To use simple upload:

  1. Create a POST request to the method's /upload URI.
  2. Add the query parameter uploadType=media.

    For example, for a bucket named myBucket:

    POST https://www.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=media

  3. Add a name query parameter to identify which resource the upload is associated with.

    For example, to specify that an object's name is myObject:

    POST https://www.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=media&name=myObject

  4. Add the file's data to the request body.

  5. Add the following HTTP headers:

    • Content-Type. Set to the MIME media type of the object being uploaded.
    • Content-Length. Set to the number of bytes you are uploading. This heading is not required if you are using chunked transfer encoding.
  6. Send the request.

Example: Sending a simple upload request

The following example shows a simple upload request to a bucket named myBucket, with the object stored as myObject:

POST https://www.googleapis.com/upload/storage/v1/b/myBucket/o?uploadType=media&name=myObject HTTP/1.1
Content-Type: image/jpeg
Content-Length: [NUMBER_OF_BYTES_IN_FILE]
Authorization: Bearer [YOUR_AUTH_TOKEN]

[JPEG_DATA]

If the request succeeds, the server returns the HTTP 200 OK status code along with the file's metadata:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "myObject"
}

Handling errors

When uploading media, be sure to follow these best practices related to error handling:

  • Resume or retry uploads that fail due to connection interruptions or any 5xx errors, including:

    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Use an exponential backoff strategy if any 5xx server error is returned when resuming or retrying upload requests. These errors can occur if a server is getting overloaded. Exponential backoff can help alleviate these kinds of problems when there is a high volume of requests or heavy network traffic.

  • When you receive an error other than a 5xx error, you do not need to use an exponential backoff strategy. Instead, limit the number of times you retry the request. For example, your code could report an error to the user after retrying a request 10 times.

For additional tips on uploading to Cloud Storage, see Uploading data to Google Cloud Storage.

What's next?

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Storage Documentation