The PUT request operation is used to add an object to a bucket.
The response indicates that the object has been successfully stored. S3 never stores partial objects: if you receive a successful response, then you can be confident that the entire object was stored.
If the object already exists in the bucket, the new object overwrites the existing object. S3 orders all of the requests that it receives. It is possible that if you send two requests nearly simultaneously, we will receive them in a different order than they were sent. The last request received is the one which is stored in S3. Note that this means if multiple parties are simultaneously writing to the same object, they may all get a successful response even though only one of them wins in the end. This is because S3 is a distributed system and it may take a few seconds for one part of the system to realize that another part has received an object update. In this release of Amazon S3, there is no ability to lock an object for writing -- such functionality, if required, should be provided at the application layer.
Example
Write some text and metadata into the "Neo" object in the "quotes" bucket:
Sample Request
PUT /quotes/Neo HTTP/1.0 x-amz-meta-family: Anderson Content-Length: 4 Authorization: AWS 15B4D3461F177624206A:xQE0diMbLRepdf3YB+FIc8F2Cy8= Date: Thu, 17 Nov 2005 07:48:33 GMT Content-Type: text/plain woah
Sample Response
HTTP/1.1 200 OK x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7 x-amz-meta-family: Anderson x-amz-request-id: 0A49CE4060975EAC Date: Thu, 17 Nov 2005 07:48:32 GMT ETag: "828ef3fdfa96f00ad9f27c383fc9ac7f" Content-Length: 0 Connection: close Server: AmazonS3
Cache-Control:Can be used to specify caching behavior along the request/reply chain. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9.
Content-Type: A standard MIME type describing the format of the contents. If none is provided, the default is binary/octet-stream. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17.
Content-Length: The size of the object, in bytes. This is required. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13.
Content-MD5: An MD-5 hash of the object's value. This is used to verify integrity of the object in transport. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.15.
Content-Disposition: Specifies presentational information for the object. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1.
Expires: Gives the date/time after which the response is considered stale. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21.
x-amz-meta-: x-amz-meta-: Any header starting with this prefix is considered user metadata. It will be stored with the object and returned when you retrieve the object. The total size of the HTTP request, not including the body, must be less than 4 KB.
The data to be stored in the object is sent in the request body.
ETag: The entity tag is an MD5 hash of the object that you can use to do conditional GET operatons using the If-Modified request tag with the GET request operation. You can also use this value to compare to your own calculated MD5 hash to ensure the object wasn't corrupted over the wire.
You must have WRITE access to the bucket to add an object.