Unclear documentation for Restoring Object from Glacier

[nitrag]

Documentation is sorely lacking for restoreObject(). There are multiple issues here.

Describe the issue

Issue aws/aws-sdk-java-v2#1: - There is a strongly typed Tier.SELECT but not "restore an archive" is not? I don't want to do a SELECT just a regular object retrieval. "Restore an Object" appears to be it's own method. Maybe these need to be separated?

Issue aws/aws-sdk-java-v2#2: Documentation is unclear wether you specify Tier in the GlacierJobParameters or RestoreRequest. It turns out it needs to be in the GlacierJobParameters but why is it even an option in RestoreRequest?

If you don't provide the correct format you can a super unhelpful error:

software.amazon.awssdk.services.s3.model.S3Exception: The XML you provided was not well-formed or did not validate against our published schema (Service: S3, Status Code: 400

Issue aws/aws-sdk-java-v2#3: The builders are not doing any sort of validation to provide helpful warnings. For instance. I can specify output location and get no warning that applies to SELECT only.

The only example I could find is for Version 1 SDK. So I lot a lot of time trying to figure out what I was doing wrong. I'm not sure but it could have even been I wasn't using valid IAM permissions. Still same XML error.

Links

https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html

[nitrag]

Actually, please change this to a Bug.

Adding description to the RestoreRequest body will cause you to get the XML exception. So many of my issues trying to determine the correct builder methods were really just because I was testing with using a description. According to docs (and sdk) this is an acceptable input.

val restoreRequest = RestoreRequest.builder()
    .days(retrievalDuration)
    .glacierJobParameters(GlacierJobParameters.builder().tier(retrievalTier).build())
    .description("PV Restore Request") // <-- this will throw XML exception
    .build()
val restoreObjectRequest = RestoreObjectRequest.builder()
    .bucket(bucket)
    .key(key)
    .restoreRequest(restoreRequest)
    .build()

here's the printed variable from debugger:

RestoreObjectRequest(
	Bucket=<purposely removed>, 
	Key=testResources/S3DownloadTestFiles/glacier.txt,
	RestoreRequest=RestoreRequest(
		Days=1, 
		GlacierJobParameters=GlacierJobParameters(
			Tier=Standard
		), 
		Description=PV-StorageService Retrieval
	)
)

[debora-ito]

• #1 and #2 are good points, #2 is very confusing. I'll reach out to the Glacier team and ask for clarifications.
• For #3, the SDK builders will not make validations, on any service. Client side validations are not maintainable in the scale of the number of aws services, so usually field validations are made when the request reaches the service. The malformed XML error message is surely not helpful, I'll ask the Glacier team to make it more clear.

[debora-ito]

Just checked, the internal ticket is still open in the Glacier team's backlog.

For visibility to other SDKs, I'm moving this to the aws-sdk repository.

[shariq-alee]

Actually, please change this to a Bug.

Adding description to the RestoreRequest body will cause you to get the XML exception. So many of my issues trying to determine the correct builder methods were really just because I was testing with using a description. According to docs (and sdk) this is an acceptable input.

val restoreRequest = RestoreRequest.builder()
    .days(retrievalDuration)
    .glacierJobParameters(GlacierJobParameters.builder().tier(retrievalTier).build())
    .description("PV Restore Request") // <-- this will throw XML exception
    .build()
val restoreObjectRequest = RestoreObjectRequest.builder()
    .bucket(bucket)
    .key(key)
    .restoreRequest(restoreRequest)
    .build()

here's the printed variable from debugger:

RestoreObjectRequest(
	Bucket=<purposely removed>, 
	Key=testResources/S3DownloadTestFiles/glacier.txt,
	RestoreRequest=RestoreRequest(
		Days=1, 
		GlacierJobParameters=GlacierJobParameters(
			Tier=Standard
		), 
		Description=PV-StorageService Retrieval
	)
)

Correct, I am also facing this issue. Any possible solutions to set description in a RestoreRequest would be helpful.

[tim-finnigan]

We were noted that the documentation regarding RestoreObject has since been updated with some clarifications added. However, the issue with Description breaking is still occurring (see: boto/boto3#3885), and Description is documented in request syntax here: https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html#API_RestoreObject_RequestBody. Will try reaching out to S3 for next steps (ref: P138915820)

[tim-finnigan]

The S3 team is continuing to track the remaining documentation fixes in their backlog. For further feedback on API documentation please use the Provide feedback at the bottom API documentation pages.

[github-actions]

This issue is now closed.

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.