aws-0.6.0: README.org

#+TITLE: Amazon Web Services for Haskell

* Introduction

The ~aws~ package attempts to provide support for using Amazon Web Services like S3 (storage), SQS (queuing) and others
to Haskell programmers. The ultimate goal is to support all Amazon Web Services.

* Installation

Make sure you have a recent GHC installed, as well as cabal-install, and installation should be as easy as:

#+BEGIN_SRC bash
$ cabal install aws
#+END_SRC

If you prefer to install from source yourself, you should first get a clone of the ~aws~ repository, and install it from
inside the source directory:

#+BEGIN_SRC bash
$ git clone https://github.com/aristidb/aws.git
$ cd aws
$ cabal install
#+END_SRC

* Using aws

** Concepts and organisation

The aws package is organised into the general =Aws= module namespace, and subnamespaces like =Aws.S3= for each Amazon Web
Service. Under each service namespace in turn, there are general support modules and and =Aws.<Service>.Commands.<Command>=
module for each command. For easier usage, there are the "bundling" modules =Aws= (general support), and =Aws.<Service>=.

The primary concept in aws is the /Transaction/, which corresponds to a single HTTP request to the Amazon Web Services.
A transaction consists of a request and a response, which are associated together via the =Transaction= typeclass. Requests
and responses are simple Haskell records, but for some requests there are convenience functions to fill in default values
for many parameters.

** Example usage

To be able to access AWS resources, you should put your into a configuration file. (You don't have to store it in a file,
but that's how we do it in this example.) Save the following in ~$HOME/.aws-keys~.

#+BEGIN_EXAMPLE
default AccessKeyID SecretKey
#+END_EXAMPLE

You do have to replace AccessKeyID and SecretKey with the Access Key ID and the Secret Key respectively, of course.

Then, copy this example into a Haskell file, and run it with ~runghc~:

#+BEGIN_SRC haskell
{-# LANGUAGE OverloadedStrings #-}

import qualified Aws
import qualified Aws.S3 as S3
import Data.Conduit
import Data.Conduit.Binary
import Data.IORef
import Data.Monoid

{- A small function to save the object's data into a file. -}
saveObject :: Aws.HTTPResponseConsumer ()
saveObject status headers source = source $$+- sinkFile "cloud-remote.pdf"

main :: IO ()
main = do
  {- Set up AWS credentials and the default configuration. -}
  cfg <- Aws.baseConfiguration
  let s3Cfg = Aws.defaultConfiguration

  {- Create an IORef to store the response Metadata (so it is also available in case of an error). -}
  metadataRef <- newIORef mempty

  {- Create a request object with S3.getObject and run the request with simpleAwsRef. -}
  Aws.simpleAwsRef cfg s3Cfg metadataRef $ S3.getObject "haskell-aws" "cloud-remote.pdf" saveObject

  {- Print the response metadata. -}
  print =<< readIORef metadataRef
#+END_SRC

You can also find this example in the source distribution in the ~Examples/~ folder.


* Frequently Asked Questions

** S3 questions

- I get an error when I try to access my bucket with upper-case characters / a very long name.

  Those names are not compliant with DNS. You need to use path-style requests, by setting ~s3RequestStyle~ in the configuration to
  ~PathStyle~. Note that such bucket names are only allowed in the US standard region, so your endpoint needs to be US standard.

* Release Notes

** 0.7 series (planned)

Feature ideas:

- Change ServiceConfiguration concept so as to indicate in the type whether this is for URI-only requests (i.e.
  awsUri)

** 0.6 series

- 0.6.0
  - API Cleanup
    - General: Use Crypto.Hash.MD5.MD5 when a Content-MD5 hash is required, instead of ByteString.
    - S3: Made parameter order to S3.putObject consistent with S3.getObject.
  - Updated dependencies:
    - conduit 0.5 (as well as http-conduit 1.5 and xml-conduit 1.0).
    - http-types 0.7.
  - Minor changes.
  - Internal changes (notable for people who want to add more commands):
    - http-types' new 'QueryLike' interface allows creating query lists more conveniently.

** 0.5 series

- 0.5.0 ::
    New configuration system: configuration split into general and service-specific parts.

    Significantly improved API reference documentation.

    Re-organised modules to make library easier to understand.

    Smaller improvements.

** 0.4 series

- 0.4.1 :: Documentation improvements.
- 0.4.0.1 :: Change dependency bounds to allow the transformers 0.3 package.
- 0.4.0 :: Update conduit to 0.4.0, which is incompatible with earlier versions.

** 0.3 series

- 0.3.2 :: Add awsRef / simpleAwsRef request variants for those who prefer an =IORef= over a =Data.Attempt.Attempt= value.
           Also improve README and add simple example.

* Resources

- [[https://github.com/aristidb/aws][aws on Github]]
- [[http://hackage.haskell.org/package/aws][aws on Hackage]] (includes reference documentation)
- [[http://aws.amazon.com/][Official Amazon Web Services website]]