Misleading argument conversion and ideas to counter this

[jeroenvandijk]

Thanks again Michael et al. for this amazing library. I'm surprised how well it works and how relevant it still is for us over the years!

I ran into this "issue" where my first guess didn't work (similar to #256). I tried to translate com.amazonaws.services.identitymanagement.model/CreateSAMLProviderRequest
to Amazonica:

(require '[amazonica.aws.identitymanagement :as iam])
(iam/create-saml-provider :name "X"
                          :saml-metadata-document: "some-xml-data")

After some inspecting I found that to get it working I had to change the argument into :s-amlmetadata-document :

(require '[amazonica.aws.identitymanagement :as iam])
(iam/create-saml-provider :name "X"
                          :s-amlmetadata-document  "some-xml-data")

To find this I had to figure out that the issue was with amazonica.core/camel->keyword and I had to figure out I had to call it as:

(#'amazonica.core/camel->keyword "sAMLMetadataDocument") ; #=>  :s-amlmetadata-document

This made me realise a couple of things:

• What an amazing library you have created here. That it normally just works as cleanly as it does
• Trying to call the Java alternative directly is scary. I preferred introspecting and monkey patching Clojure code.
• This is not for beginners
• Maybe we could add a tools for when things don't work as expected or just as documentation (so I don't have to go the java documentation at all. For example be able to list functions with their signature per namespace. A public function like (#'iam/show-functions) but with signatures added too.

What do you think?

[mcohen01]

Thanks for the kind words Jeroen. Unfortunately the lack of docs has been the Achilles heel of this library from the beginning. Keeping the Javadocs open in the browser is a poor workaround. Every now and then someone has suggested some promising improvement, such as reading in the AWS json configs, but no one has followed through with that non-trivial work. Sadly, I haven't written Clojure code in a long time, so I'm probably not up to a task like that.

[jeroenvandijk]

Thanks for the quick response Michael. Do you have a link to the AWS json configs by any chance? For Cloudformation usage I've used an AWS schema to generate clojure specs. In combination with expound and spell-spec this works like a charm. Maybe something similar could be done by using your introspection functions. I'll try to create a working example.

[mcohen01]

I think the json files should already be on the classpath, in aws-java-sdk-models. See portkey-cloud/aws-clj-sdk@c7236c1 for an example

[jeroenvandijk]

I have made a proof of concept for using introspection to create docs https://gist.github.com/jeroenvandijk/6251424fed5e06b7427b6df20a15116e

Could easily be used to create specs (with some effort of course) :)

[jeroenvandijk]

Thanks for the pointer to the json extraction Michael. I've been able to extract the json. It looks it could be useful, but my guess is that this approach will require more work than the introspection method. I think you will basically re-create the AWS sdk in Clojure (like aws-clj-sdk). I'll give one of the approaches a go in the near future.

Code to read the json: https://gist.github.com/jeroenvandijk/6251424fed5e06b7427b6df20a15116e#file-json_model_introspection-clj

The actual json:
https://gist.github.com/jeroenvandijk/6251424fed5e06b7427b6df20a15116e#file-example_model-json