The Wayback Machine - https://web.archive.org/web/20190710165225/https://docs.aws.amazon.com/AmazonS3/latest/API/RESTBucketPUTVersioningStatus.html
Sign In to the Console
Amazon Simple Storage Service
API Reference (API Version 2006-03-01)

AWS Documentation » Amazon Simple Storage Service (S3) » API Reference » Operations on Buckets » PUT Bucket versioning

PUT Bucket versioning

Description

This implementation of the PUT operation uses the versioning subresource to set the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

You can set the versioning state with one of the following values:

  • Enabled—Enables versioning for the objects in the bucket

    All objects added to the bucket receive a unique version ID.

  • Suspended—Disables versioning for the objects in the bucket

    All objects added to the bucket receive the version ID null.

If the versioning state has never been set on a bucket, it has no versioning state; a GET versioning request does not return a versioning state value.

If the bucket owner enables MFA Delete in the bucket versioning configuration, the bucket owner must include the x-amz-mfa request header and the Status and the MfaDelete request elements in a request to set the versioning state of the bucket.

Important

If you have an object expiration lifecycle policy in your non-versioned bucket and you want to maintain the same permanent delete behavior when you enable versioning, you must add a noncurrent expiration policy. The noncurrent expiration lifecycle policy will manage the deletes of the noncurrent object versions in the version-enabled bucket. (A version-enabled bucket maintains one current and zero or more noncurrent object versions.) For more information, see Lifecycle and Versioning in the Amazon Simple Storage Service Developer Guide.

For more information about creating a bucket, see PUT Bucket. For more information about returning the versioning state of a bucket, see GET Bucket Versioning Status.

Requests

Syntax

PUT /?versioning HTTP/1.1
Host: BucketName.s3.amazonaws.com
Content-Length: length
Date: date
Authorization: authorization string (see Authenticating Requests (AWS Signature Version
		4))
x-amz-mfa: [SerialNumber] [TokenCode]

<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> 
  <Status>VersioningState</Status> 
  <MfaDelete>MfaDeleteState</MfaDelete>
</VersioningConfiguration>

Note the space between [SerialNumber] and [TokenCode].

Request Parameters

This implementation of the operation does not use request parameters.

Request Headers

Name Description Required
x-amz-mfa

The value is the concatenation of the authentication device's serial number, a space, and the value displayed on your authentication device.

Type: String

Default: None

Condition: Required to configure the versioning state if versioning is configured with MFA Delete enabled.

Conditional

Request Elements

Name Description Required
Status

Sets the versioning state of the bucket.

Type: Enum

Valid Values: Suspended | Enabled

Ancestor: VersioningConfiguration

 No
MfaDelete

Specifies whether MFA Delete is enabled in the bucket versioning configuration. When enabled, the bucket owner must include the x-amz-mfa request header in requests to change the versioning state of a bucket and to permanently delete a versioned object.

Type: Enum

Valid Values: Disabled | Enabled

Ancestor: VersioningConfiguration

Constraint: Can only be used when you use Status.

No
VersioningConfiguration

Container for setting the versioning state.

Type: Container

Children: Status

Ancestor: None

 Yes

Responses

Response Headers

This implementation of the operation uses only response headers that are common to most responses. For more information, see Common Response Headers.

Response Elements

This implementation of the operation does not return response elements.

Special Errors

This implementation of the operation does not return special errors. For general information about Amazon S3 errors and a list of error codes, see Error Responses.

Examples

Sample Request

The following request enables versioning for the specified bucket.

PUT /?versioning HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 01 Mar  2006 12:00:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124
 
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> 
  <Status>Enabled</Status> 
</VersioningConfiguration>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar  2006 12:00:00 GMT

Sample Request

The following request suspends versioning for the specified bucket.

PUT /?versioning HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124
 
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> 
   <Status>Suspended</Status> 
</VersioningConfiguration>

Sample Response

HTTP/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar  2006 12:00:00 GMT

Sample Request

The following request enables versioning and MFA Delete on a bucket.

PUT /?versioning HTTP/1.1
Host: bucket.s3.amazonaws.com
Date: Wed, 12 Oct 2009 17:50:00 GMT
x-amz-mfa:[SerialNumber] [TokenCode]
Authorization: authorization string
Content-Type: text/plain
Content-Length: 124
 
<VersioningConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/"> 
   <Status>Enabled</Status> 
   <MfaDelete>Enabled</MfaDelete>
</VersioningConfiguration>

Note the space between [SerialNumber] and [TokenCode] and that you must include Status whenever you use MfaDelete.

Sample Response

HTTPS/1.1 200 OK
x-amz-id-2: YgIPIfBiKa2bj0KMg95r/0zo3emzU4dzsD4rcKCHQUAdQkf3ShJTOOpXUueF6QKo
x-amz-request-id: 236A8905248E5A01
Date: Wed, 01 Mar  2006 12:00:00 GMT

Location: /colorpictures
Content-Length: 0
Connection: close
Server: AmazonS3