Add beginner friendly examples

[kingparra]

Hello! I'm relatively new to Haskell, but experienced with the AWS SDK (using Python and Node).

When I look at examples/EC2.hs, there are a lot of new abstractions to learn. For example, I don't know any of these language extensions other than OverloadedString and haven't worked with Conduit, Lens, or Bytestring before.

Can you add an example that only uses Amazonka and Prelude? Some comments and explicit imports would also be nice.

[endgame]

Question: Did you find the example in the Amazonka module haddocks. Was it any use to you?

Are you interested in collaborating on this? It's relatively rare for us to have a perspective from an AWS-literate Haskell newbie, and I'd really like to capture something that makes sense to people with your background. At the moment, the examples are all written in a bunch of different ways, to show different alternatives, but there's no guidance for the reader.

I'm on the road at the moment, but I'll go through the examples as they are and see if I can at least remove any unnecessary language extensions.

Prelude is not enough, because that doesn't give you any of the data structures used in requests/responses. I take the spirit of this question as "can we use Prelude only? If not, can we use package base only? If not, can we use bundled libraries only (e.g. bytestring, containers, text)?" — I think the answer is "no", even for the last, but we can provide some simpler examples than what we have now.

As to the libraries that you've called out:

• ByteString is kinda unavoidable — it's just Haskell's "chunk of bytes" type. I think you'll hit it pretty early on in your Haskell work as soon as you do pretty much anything nontrivial.
• Conduit is necessary if you want Amazonka to automatically handle a paginated request (like s3:ListObjects); the Conduit is how we interleave the requests and returns of each requested page. However, we can convert the conduit to a list ASAP and have most of the code just working on the result as a list (runConduit (result .| sinkList) or something, off the top of my head).
• lens is hard to skip, but doable — it makes updating deeply nested records a lot nicer, as well as pulling out bits of responses through several layers of Maybe (AWS are not always disciplined about marking request/response fields as required in their service definitions, so we have a lot of Maybes.) But we could probably get something workable using record updates and pattern matches.

We could probably do that with a few examples from well-understood AWS services. Maybe we should have simple examples for lambda:Invoke, s3:GetObject and s3:PutObject. Streaming file I/O means we'll need conduits for the latter two, but they're so fundamental to AWS use that we should provide simple, copyable code to just upload/download a file. Bonus: we probably want presigned versions of the latter two, also.

[kingparra]

Hello Brendan,

I'd love to work together on this! It seems like a great opportunity to learn, and it can help improve the docs for other newbies. Win win.

I have to admit that I went straight to the examples first. Usually the AWS SDK is similar enough between languages that I can immediately draw parallels, so the typical pattern for me is to check the examples first, make sure I can build the code, and then do a tutorial before getting into reference docs. Looking at the haddocks I can see there is some tutorial-style material in there that I overlooked.

Looking back on it, I think it makes sense to keep conduit and lens in the examples. I just had a bit of an information overload moment when trying to get started with lens.

How about I send you a user story with my motivation for visiting the documentation/gh repo, and the reactions/questions I had along the way? Then I can suggest some inline comments for the examples, or work on writing a "quick-start tutorial for [service]" guide.

I also think it would be really helpful to have a few tutorial style articles linked from the front page of https://amazonka.brendanhay.nz/.

Sincerely,

Chris King-Parra

On Wednesday, August 7th, 2024 at 11:44 PM, endgame @.***> wrote:

Question: Did you find the example in the Amazonka module haddocks. Was it any use to you?

Are you interested in collaborating on this? It's relatively rare for us to have a perspective from an AWS-literate Haskell newbie, and I'd really like to capture something that makes sense to people with your background. At the moment, the examples are all written in a bunch of different ways, to show different alternatives, but there's no guidance for the reader.

I'm on the road at the moment, but I'll go through the examples as they are and see if I can at least remove any unnecessary language extensions.

Prelude is not enough, because that doesn't give you any of the data structures used in requests/responses. I take the spirit of this question as "can we use Prelude only? If not, can we use package base only? If not, can we use bundled libraries only (e.g. bytestring, containers, text)?" — I think the answer is "no", even for the last, but we can provide some simpler examples than what we have now.

As to the libraries that you've called out:

• ByteString is kinda unavoidable — it's just Haskell's "chunk of bytes" type. I think you'll hit it pretty early on in your Haskell work as soon as you do pretty much anything nontrivial.
• Conduit is necessary if you want Amazonka to automatically handle a paginated request (like s3:ListObjects); the Conduit is how we interleave the requests and returns of each requested page. However, we can convert the conduit to a list ASAP and have most of the code just working on the result as a list (runConduit (result .| sinkList) or something, off the top of my head).
• lens is hard to skip, but doable — it makes updating deeply nested records a lot nicer, as well as pulling out bits of responses through several layers of Maybe (AWS are not always disciplined about marking request/response fields as required in their service definitions, so we have a lot of Maybes.) But we could probably get something workable using record updates and pattern matches.

We could probably do that with a few examples from well-understood AWS services. Maybe we should have simple examples for lambda:Invoke, s3:GetObject and s3:PutObject. Streaming file I/O means we'll need conduits for the latter two, but they're so fundamental to AWS use that we should provide simple, copyable code to just upload/download a file. Bonus: we probably want presigned versions of the latter two, also.

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>