Parameter is not listed as REQUIRED

[Brettles]

Describe the issue

On https://docs.aws.amazon.com/boto3/latest/reference/services/s3/client/put_bucket_replication.html the Prefix parameter is not listed as REQUIRED but calls to put_bucket_replication will fail without it.

Links

https://docs.aws.amazon.com/boto3/latest/reference/services/s3/client/put_bucket_replication.html

[RyanFitzSimmonsAK]

Hi @Brettles, thanks for reaching out. I believe the Prefix parameter is not marked as required because the operation requires that either Prefix or Filter is present, but not both. In my testing, I was able to successfully add bucket replication with the Filter parameter and not the Prefix parameter. Please note that "when you add the Filter element in the configuration, you must also add the following elements: DeleteMarkerReplication, Status, and Priority."

Please let me know if you have any follow-up questions. Thanks!

[Brettles]

Understood - is there a (standard) way (within the AWS documentation) to make that distinction at the place where the parameter is documented? Otherwise a casual reader (guilty!) will miss that and be wondering what needs to be included.

In this case, searching for Prefix (and again with a casual read - i.e. not looking for the "when you add the Filter element" part) it's easy to miss that one or the other must be specified.

[RyanFitzSimmonsAK]

In general, I recommend using the Boto3 API reference in conjunction with the service API reference (i.e https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketReplication.html). The service API reference may have additional details that get omitted from the Boto3 docs, particularly with structures (such as https://docs.aws.amazon.com/AmazonS3/latest/API/API_ReplicationRule.html).

In this case, looking at the service API reference would have revealed that the Prefix parameter is deprecated, presumably since you're expected to use the Filter parameter instead.

You are correct that this documentation is lacking detail though. This nuance should be documented. If you like, I can ticket the service team to try and get this updated.

[Brettles]

I see the challenge here though: Duplicating information across multiple places leads to more difficult maintenance. In this case, more clarity would be good.