S3 batch - arg is required but autopopulated

[mdavis-xyz]

Describe the issue

For the S3 batch create_job function, the ClientRequestToken docs say:

ClientRequestToken (string) --

[REQUIRED]

An idempotency token to ensure that you don't accidentally submit the same request twice. You can use any string up to the maximum length.

This field is autopopulated if not provided.

If the field is autopopulated if not provided, then that means it's ok to not provide it, i.e. it is not required.

Please remove [REQUIRED] from the docs.

(Note, the This field is autopopulated if not provided. part is not present in the underlying API docs. So I assume boto3 added this and that boto3 is doing the autopopulation, which is a great feature, but could be documented more clearly.)

Links

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3control.html#S3Control.Client.create_job

https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateJob.html#AmazonS3-control_CreateJob-request-ClientRequestToken

[kdaily]

Hi @mdavis-xyz,

Thanks for posting. The 'required' status is modeled in the API here:

https://github.com/boto/botocore/blob/60abb9ca5f6596acc7ad64754e2d0c9c993c4a16/botocore/data/s3control/2018-08-20/service-2.json#L1344

The addition of the extra text you're seeing is also modeled via the idempotencyToken property on that parameter:

https://github.com/boto/botocore/blob/60abb9ca5f6596acc7ad64754e2d0c9c993c4a16/botocore/data/s3control/2018-08-20/service-2.json#L1372

I agree that 'required' takes on a different meaning here, as the user does not need to necessarily take an action. I'm not sure what could make that more clear - the S3 service wouldn't want to remove either of these options, because from the perspective of the operation, the value is required.

What would you suggest to make it more clear?

[mdavis-xyz]

To make it more clear, I would suggest removing the word "required" for fields with "idempotencyToken":true.

These are docs for boto3, the python library. If there is a mismatch between the python SDK interface and the API, the docs should reflect the python interface.

Consider the similar case of datetime fields. The API does not take datetimes, only strings (of datetimes). The python docs show datetime objects, not strings. Having auto-populated fields is the same thing. The docs should show me how to use the python library boto3, not the raw API, because the people reading these docs are not using the raw API.

[mdavis-xyz]

I just received a response to a AWS support ticket about batch operations. The support person wrote an example for me where they explicitly generated a token to pass to this field for a create_job call with boto3. So even the experts who use this every day don't realise that it's not required.

It's great that boto3 generates the token for us. It would be a shame if that good work was wasted because people didn't realise that boto3 is that smart.