max-keys option is undocumented for s3api list-object-versions

[iainelder]

Describe the issue

The list-object-versions documentation refers to max-keys in the descriptions of other options.

The max-keys option needs its own description and an example.

The max-items option is similar and so sometimes people come to GitHub to ask for how to make max-items act like max-keys.

Today those issues are the best documentation I can find for max-keys.

Links

• https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/list-object-versions.html
• list-object-versions --page-size and --max-items ignored for DeleteMarkers #8131
• s3api list-object-versions '--max-items' account for "Versions" but not "DeleteMarkers" #2525

[RyanFitzSimmonsAK]

Hi @iainelder, thanks for reaching out. There's a few different things going on here to result in this behavior.

The AWS CLI documentation generally will hide service pagination parameters in favor of its own parameters ( --max-items being one such parameter). There are plenty of examples of this, such as describe-instances hiding max-results, or list-roles hiding marker. This is done so that pagination using the CLI is normalized across services. However, the CLI doesn't actually stop those parameters from being sent, hence why max-keys is functional for the S3 operations.

As I'm sure you saw in the issues you linked, there's some weird behavior around operations with multiple paginatable keys. list-object-versions has three, seen here. In the event of multiple paginatable keys, --max-items only applies to the first in that list. So that's why we're in situation where this undocumented parameter is sometimes more useful than the pagination parameters we replaced it with.

We do already have a backlog item to better document this behavior by clarifying which response element is affected by --max-items. I've raised this issue with the team. Given that this is a duplicate issue, I'm going to close this in favor of the older issue (#2555). Hope that helps, and please let me know if you have any further questions.

[github-actions]

Greetings! It looks like this issue hasn’t been active in longer than five days. We encourage you to check if this is still an issue in the latest release. In the absence of more information, we will be closing this issue soon. If you find that this is still a problem, please feel free to provide a comment or upvote with a reaction on the initial post to prevent automatic closure. If the issue is already closed, please feel free to open a new one.