generate_presigned_url docs missing links and explanations

[mdavis-xyz]

Describe the issue

For most boto functions, each documentation page has something like:

See also: AWS API Documentation

e.g. s3.delete_object.

But for S3 generate_presigned_url it doesn't have a link to the raw API documentation.

Also, most parameters aren't completely defined.

• e.g. ClientMethod. What's that? Is that get, Get, GET, or something else?
• Params - what is the meaning of this?
• HttpMethod - hang on, this sounds the same as ClientMethod. Is this the GET part? (Or get, or Get). Or is this https vs http?
• Hmm, there's no parameters for bucket or key. Do they go in Params? If so, is it Bucket or BucketName, or a path like s3://bucket/path/file.txt?

Usually when the boto docs are ambiguous in this way (e.g. missing possible enum values) I just click on the link to the raw API documentation. But that link is omitted.

I'm not able to even figure out where that link should point to. It seems this API call is not documented by AWS?

#3048 was related, but expired due to staleness.

Links

https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/generate_presigned_url.html

[RyanFitzSimmonsAK]

HI @mdavis-xyz, thanks for reaching out. This documentation has a lot more details than the reference guide, so it'd recommend checking that out, but I'll go over your questions here as well.

But for S3 generate_presigned_url it doesn't have a link to the raw API documentation.

The reason that generate_presigned_url is missing an API reference is because it isn't actually an API call, but instead is done locally. If you enable debug logs and generate a presigned url, you can see there isn't actually a response since a request isn't being made.

Here's an example provided in the aforementioned documentation.

import boto3
    url = boto3.client('s3').generate_presigned_url(
    ClientMethod='get_object', 
    Params={'Bucket': 'BUCKET_NAME', 'Key': 'OBJECT_KEY'},
    ExpiresIn=3600)

e.g. ClientMethod. What's that? Is that get, Get, GET, or something else?

ClientMethod is the operation you want your url to execute. You can use generate_presigned_url to upload files as well, so it doesn't necessarily have to be a GET.

Params - what is the meaning of this?
Hmm, there's no parameters for bucket or key. Do they go in Params? If so, is it Bucket or BucketName, or a path like s3://bucket/path/file.txt?

Yes, those parameters go in Params as a dictionary, where the name of the parameter is a key, and the desired value for that parameter is a value. The correct format for each key can be found on the reference guide page for the ClientMethod you've chosen.

HttpMethod - hang on, this sounds the same as ClientMethod. Is this the GET part? (Or get, or Get). Or is this https vs http?

You are correct, this parameter refers to the HTTP method, including 'GET', 'PUT', and 'POST. You don't typically need to specify this, since it defaults to the correct method for the ClientMethod you've specified.

I hope that answers all your questions. Regarding improvements to the documentation, do you think that adding an example to the reference guide like the one I posted would be helpful?

[mdavis-xyz]

The documentation you linked to makes it sound like this is just a normal API operation.

do you think that adding an example to the reference guide like the one I posted would be helpful?

Yes, but I think it would be more helpful to just document each argument to the same level that is done for other calls.

• label arguments as mandatory if they are mandatory. Currently they're all shown as not mandatory, which sounds wrong.
• ClientMethod: List all valid string enum values. (get_object. put_object. Anything else? The docs mentioned multi-part uploads. I don't understand how that would work. Will the call return two different URLs?)
• Params - exhaustively list everything that can go inside this, and state which ones are optional. e.g. Is Key mandatory, or is there some kind of list_bucket presigned URL which can work without Key? And can I put VersionId in there? (Boto3's S3 calls are not consistent in terms of where you put VersionId.) What about any other arguments, like RequestPayer, Tags etc?
• ExpiresIn - state the maximum value. Or link to the page in the docs that states the maximum value
• HttpMethod - List all valid string enum values. Or state whether it wants GET vs Get vs get.

[RyanFitzSimmonsAK]

While I wait to hear back about improving the reference guide, I do want to mention a much more detailed piece of documentation that I didn't link in my original reply. I hope that clears up a bit of confusion in the meantime.

[mdavis-xyz]

Just checking, who are you waiting on about improving the reference guide? I responded with improvement suggestions in my last comment. You're not waiting on me, right?

That detailed doc is more helpful. Although still not comprehensive enough. But it would be worth linking from here to here.

I still don't see how I can specify something like version id. Is the Params field of generate_presigned_url supposed to align exactly to the args of a normal get_object call? (e.g. 'VersionId': v not 'ExtraArgs': {'VersionId': v})

What about fields like PartNumber and Range? Do those go into the generate_presigned_url? I thought those are normally passed as header fields. So do I need to generate a URL without those parameters, and tell the other client to add those parameters?

One of the things I don't get is how to know what HTTP method to use. That last link says that the SDK will figure it out based on the non-HTTP method. But I need to tell the unauthorised client what method to use to access the pre-signed url after it's been generated. e.g. it says you can do presigned urls for list_buckets. What method does the client use for that? GET is intuitive. However I know that in general AWS API calls are all POST, even for read-only calls you expect to be a GET. So how do I know whether a specific S3 API aligns to the Amazon standard, or the normal HTTP standard?

[RyanFitzSimmonsAK]

Closing in favor of a more recent duplicate issue : #3901

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

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.

[jim-meyer]

@RyanFitzSimmonsAK any update on actually implementing the useful suggestions that @mdavis-xyz spelled out about documenting exactly what values are allowed for each of these parameters somewhere like https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/generate_presigned_url.html?
The information at https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-presigned-urls.html is only somewhat helpful in that it didn't show up as a top hit for the google searches I did. AND I tend to distrust sample snippets based on past experiences with other AWS provided sample code.