[bug#53765,13/17] gnu: Add clojure-com-cognitect-aws-api.

* gnu/packages/clojure.scm (clojure-com-cognitect-aws-api): New variable.
---
 gnu/packages/clojure.scm | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

Reily Siegel schreef op do 03-02-2022 om 19:26 [-0500]:
> +    (synopsis "aws-api is a Clojure library which provides programmatic access
> +to AWS services from your Clojure program")

It seems irrelevant that it's mine or yours or someone else's, I would
replace 'your Clojure program' with 'Clojure'.

Also, introduce the acronym AWS before using it.

Greetings,
Maxime.

Reily Siegel schreef op do 03-02-2022 om 19:26 [-0500]:
> @code{aws-api} is an idiomatic, data-oriented Clojure
> +library for invoking AWS APIs.

From ‘Synopses and Descriptions’:

Please avoid marketing phrases such as “world-leading”,
“industrial-strength”, and “next-generation”, and avoid superlatives
like “the most advanced”—they are not helpful to users looking for a
package and may even sound suspicious.  Instead, try to be factual,
mentioning use cases and features.

I'm referring to 'idiomatic' and 'data-oriented' which is rather vague
and subjective.

Greetings,
Maxime.

Reily Siegel schreef op do 03-02-2022 om 19:26 [-0500]:
> +    (description "@code{aws-api} is an idiomatic, data-oriented Clojure
> +library for invoking AWS APIs.
> 
What's an ‘AWS API’?  How do I now if I have one?  Some context is
required here.

>   While the library offers some helper and
> +documentation functions you'll use at development time, the only functions you
> +ever need at runtime are @code{client}, which creates a client for a given
> +service and @code{invoke}, which invokes an operation on the
> +service.
> 

How can this description now I will never need these helper functions?
If they are unneeded, why are they included at all?

>  @code{invoke} takes a map and returns a map, and works the same way
> +for every operation on every service.")

Anyway, descriptions aren't the place to describe the API, that's for
the documentation of clojure-com-cognitect-aws-api.  Instead, keep in
mind:

‘[...], try to be factual, mentioning use cases and features.’

‘Keep in mind that the synopsis must be meaningful for a very wide
audience.  For example, “Manipulate alignments in the SAM format” might
make sense for a seasoned bioinformatics researcher, but might be
fairly unhelpful or even misleading to a non-specialized audience.  It
is a good idea to come up with a synopsis that gives an idea of the
application domain of the package.  In this example, this might give
something like “Manipulate nucleotide sequence alignments”, which
hopefully gives the user a better idea of whether this is what they are
looking for.’

Greetings,
Maxime.

Maxime Devos <maximedevos@telenet.be> writes:

> Reily Siegel schreef op do 03-02-2022 om 19:26 [-0500]:
>> @code{aws-api} is an idiomatic, data-oriented Clojure
>> +library for invoking AWS APIs.

> I'm referring to 'idiomatic' and 'data-oriented' which is rather vague
> and subjective.
Data-oriented has a rather specific meaning in the Clojure community,
that is that the API is declarative and operates on plain Clojure data
structures, as opposed to using Macros or a class-based system. I will
update the descriptions and synopses that were mentioned in other
replies, and submit a new version of the patch.

Reily Siegel schreef op ma 07-02-2022 om 13:09 [-0500]:
> Data-oriented has a rather specific meaning in the Clojure community,
> that is that the API is declarative and operates on plain Clojure data
> structures, as opposed to using Macros or a class-based system.

OK, though I don't see how it can be declarative -- it's a library
for ‘invoking AWS APIs’, which seems rather imperative, at least
procedural.

Greetings,
Maxime.

Maxime Devos <maximedevos@telenet.be> writes:

> OK, though I don't see how it can be declarative -- it's a library
> for ‘invoking AWS APIs’, which seems rather imperative, at least
> procedural.
Let me compare this library and the official Java AWS SDK.

#+BEGIN_SRC java
// Create a GetItemRequest instance
GetItemRequest request = GetItemRequest.builder()
                       .key(keyToGet)
                       .tableName(tableName)
                       .build();

// Invoke the DynamoDbAsyncClient object's getItem
java.util.Collection<AttributeValue> returnedItem = client.getItem(request)
                                                  .join()
                                                  .item()
                                                  .values();
#+END_SRC

#+BEGIN_SRC clojure
(aws/invoke s3 {:op :GetObject :request {:Bucket bucket-name :Key "hello.txt"}})
#+END_SRC

The Java API programatically creates a Request object, when is then
modified by several methods to set the options, before being invoked.
The Clojure API, on the other hand, specifies the operation
declaratively using plain Clojure data structures (in this case,
keywords, strings, and maps), before calling invoke on that
specification. The declarative part is in how the API is interacted
with, not necessarily what happens in the library internals or over the
wire.

Examples from the respective documentations of each project.