Undocumented key-marker parameter in s3api list-object-versions

[iainelder]

Confirm by changing [ ] to [x] below to ensure that it's a bug:

• I've gone though the User Guide and the API reference
• I've searched for previous similar issues and didn't find any solution

Describe the bug
The documentation for the aws s3api list-object-versions command does not fully describe the key-marker

SDK version number
aws-cli/1.18.154 Python/3.6.9 Linux/5.4.0-48-generic botocore/1.18.13

Platform/OS/Hardware/Device
Ubuntu 18.04

To Reproduce (observed behavior)

View documentation for the command.

aws s3api list-object-versions help

Search for "key-marker".

/key-marker

The request parameter is referenced in the output section, but it is not listed as one of the parameters in the synopsis and the options.

Synopsis:

SYNOPSIS
            list-object-versions
          --bucket <value>
          [--delimiter <value>]
          [--encoding-type <value>]
          [--prefix <value>]
          [--expected-bucket-owner <value>]
          [--cli-input-json <value>]
          [--starting-token <value>]
          [--page-size <value>]
          [--max-items <value>]
          [--generate-cli-skeleton <value>]

Output:

       NextKeyMarker -> (string)
          When the number of responses exceeds the value of MaxKeys , NextKey-
          Marker  specifies  the  first  key  not  returned that satisfies the
          search criteria. Use this value for the key-marker request parameter
          in a subsequent request.

Expected behavior

The parameter should be documented in the synopsis and the options.

Additional context

It's a particularly unfortunate omission because most of the s3api commands that work with objects take --key as a parameter, which I naively passed when using this command for the first time. awscli by design presumably matches --key to --key-marker or something similar.

It confused me for quite a long time.

The correct parameter to use in my case was --prefix.

[kdaily]

Hi @iainelder, sorry to hear about the confusion! Your intuition is correct. Here's a good comment on a previous issue that explains what's happening:

#2555 (comment)

So, even though pagination-related parameters are normalized across AWS services in the CLI, they're still valid parameters. I'm going to leave this open as a discussion point to talk about this more explicitly in a documentation page.

[iainelder]

Thanks for the response and the link to the explanation.

It looks like the author of #2555 made the same mistake I did, using --key instead of --prefix.

I can't tell from the comment you linked whether the --key-marker parameter is undocumented on purpose or on omission.

In any case, I don't know enough about the awscli internals to have a strong opinion about this, so I will defer to your discussion. :-)

[kdaily]

It is intentionally left out of the documentation to provide a more unified experience for pagination. That being said, the omission of the parameters could be explained somewhere separately. The prefix matching applied to parameter names could be better described as well.