[DRAFT] Elixir Optional parameters

[Doerge]

This PR:

• Moves optional positional parameters to a Keywordlist.

• Validates optional param names (only for url/query/header params, not for HTTP bodies).

• Documents optional parameters and their types, as best as possible (smithy is a mess sometimes).

• Improves docs formatting.

• Improves typespecs.

• Only includes the beginning of the AWS docs for a method, and links (as best as possible) to the online page instead.

• Improves formatting slightly of AWS docs.

• Adds guards for required params.

• Guards on HTTP bodies (binary vs map).

Updated 19/7/2024

Original:
https://github.com/aws-beam/aws-elixir/blob/master/lib/aws/generated/s3.ex#L8374
Latest:
https://github.com/Doerge/aws-elixir/blob/dev/optional-parameters-wip-2/lib/aws/generated/s3.ex

TODO:

• Add generation of docs for request with HTTP body.
• Guards for required params.
• Check if req_body_as_binary is ever passed as param at callsite, and if it should be fixed.
• Delete superfluous typespecs in the top of files.
• Fix upload_part input detected as optional here: https://github.com/Doerge/aws-elixir/blob/84e4215e5d4e136817d19a1a581444e8e620b157/lib/aws/generated/s3.ex#L14641

[Doerge]

I'd still like to validate the optional parameters with Keyword.validate!, but because the optional params are popped off, and then the rest is passed down to the client, this is not possible. I.e. if an optional param is misspelled, it just get's sent to the client.

Possible solutions:
a. Group all client-related params under a keyword like client_opts.
b. Add a second optional positional parameter client_opts that is passed down to the client.

I think option a. is easier, and cleaner. Will draft that up.
Note: Tesla uses the adapter keyword.

[yordis]

Since the operations already take a client argument, couldn't you just put the client opts there?

client
|> put_opts() # do things before
|> get_bucket_website() # only about operations

[Doerge]

Ah, that's actually a really good idea! Completely bypasses the issue.
I'd probably add that as a little utility function:

defmodule AWS.Client do
  [...]
  def put_http_opts(%__MODULE__{} = client, opts) do
      {http_client, default_opts} = client.http_client
      final_opts = Keyword.merge(default_opts, opts)
    
      client
      |> AWS.Client.put_http_client({http_client, opts})
  end
end

my_client
|> AWS.Client.put_http_opts(foo: false)
|> get_bucket_website()

What do you think?

[yordis]

That works; it is similar to https://github.com/elixir-tesla/tesla/blob/d39d575af3edb87cc156b803317ebb7f7670b45f/lib/tesla.ex#L182 So some extent, you are chasing something similar to Tesla but one layer above

[Doerge]

I went ahead with this and now have optional parameter validation:
https://github.com/Doerge/aws-elixir/blob/140deecfb1387b14bf5da4c683b4086b44bf9629/lib/aws/generated/s3.ex#L11621

Basic tests here: https://github.com/Doerge/aws-elixir/blob/dev/optional-parameters-wip-2/test/aws/generated/s3_test.exs

[Doerge]

@onno-vos-dev I'm struggleing with this part. Can you chime in here? I'd like to figure out if a body is required or not.

Optional example:

        "com.amazonaws.s3#CreateBucketRequest": {
            "type": "structure",
            "members": {
                [...]
                "CreateBucketConfiguration": {
                    "target": "com.amazonaws.s3#CreateBucketConfiguration",
                    "traits": {
                        "smithy.api#documentation": "<p>The configuration information for the bucket.</p>",
                        "smithy.api#httpPayload": {},
                        "smithy.api#xmlName": "CreateBucketConfiguration"
                    }
                },

Required example:

        "com.amazonaws.s3#UploadPartRequest": {
            "type": "structure",
            "members": {
                "Body": {
                    "target": "com.amazonaws.s3#StreamingBlob",
                    "traits": {
                        "smithy.api#default": "",
                        "smithy.api#documentation": "<p>Object data.</p>",
                        "smithy.api#httpPayload": {}
                    }
                },

Required example:

        "com.amazonaws.apigatewayv2#CreateApiRequest": {
            "type": "structure",
            "members": {
                "ApiKeySelectionExpression": {
                    "target": "com.amazonaws.apigatewayv2#SelectionExpression",
                    "traits": {
                        "smithy.api#documentation": "...",
                        "smithy.api#jsonName": "apiKeySelectionExpression"
                    }
                },
               [...]
           }
           "traits": {
                "smithy.api#documentation": "<p>Creates a new Api resource to represent an API.</p>",
                "smithy.api#input": {}
            }

I'm not sure if these examples are even covering all cases, and searching for jsonName feels very dirty, but I don't think I'm deep enough into the smithy spec to see a better way?