README.md

# httpc-aws

A light-weight, relatively unopinionated AWS API client for Erlang 21.0+.

[![Build Status](https://travis-ci.org/gmr/httpc-aws.svg?branch=master)](https://travis-ci.org/gmr/httpc-aws)
[![codecov.io](https://codecov.io/github/gmr/httpc-aws/coverage.svg?branch=master)](https://codecov.io/github/gmr/httpc-aws?branch=master)

## Supported Erlang Versions

  - 21.0

## Configuration

Configuration for *httpc-aws* is can be provided in multiple ways. It is designed
to behave similarly to the [AWS Command Line Interface](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
with respect to providing region and configuration information. Additionally it
has two methods, ``httpc_aws:set_region/1`` and ``httpc_aws:set_credentials/2``
to allow for application specific configuration, bypassing the automatic configuration
behavior.

### Configuration Precedence

The configuration values have the following precedence:

 - Explicitly configured via API
 - Environment variables
 - Configuration file
 - EC2 Instance Metadata Service where applicable

### Credentials Precedence

The credentials values have the following precedence:

 - Explicitly configured via API
 - Environment variables
 - Credentials file
 - EC2 Instance Metadata Service

### Environment Variables

As with the AWS CLI, the following environment variables can be used to provide
configuration or to impact configuration behavior:

 - ``AWS_DEFAULT_PROFILE``
 - ``AWS_DEFAULT_REGION``
 - ``AWS_CONFIG_FILE``
 - ``AWS_SHARED_CREDENTIALS_FILE``
 - ``AWS_ACCESS_KEY_ID``
 - ``AWS_SECRET_ACCESS_KEY``

## API Methods

  Method                             | Description
 ------------------------------------|--------------------------------------------------------------------------------------------
 ``httpc_aws:set_region/1``          | Manually specify the AWS region to make requests to.
 ``httpc_aws:set_credentials/2``     | Manually specify the request credentials to use.
 ``httpc_aws:refresh_credentials/0`` | Refresh the credentials from the environment, filesystem, or EC2 Instance Metadata service.
 ``httpc_aws:get/2``                 | Perform a GET request to the API specifying the service and request path.
 ``httpc_aws:get/3``                 | Perform a GET request specifying the service, path, and headers.
 ``httpc_aws:post/4``                | Perform a POST request specifying the service, path, headers, and body.
 ``httpc_aws:request/5``             | Perform a request specifying the service, method, path, headers, and body.
 ``httpc_aws:request/6``             | Perform a request specifying the service, method, path, headers, body, and ``httpc:http_options().``
 ``httpc_aws:request/7``             | Perform a request specifying the service, method, path, headers, body,  ``httpc:http_options()``, and override the API endpoint.


## Example Usage

The following example assumes that you either have locally configured credentials or that
you're using the AWS Instance Metadata service for credentials:

```erlang
application:start(httpc_aws).
{ok, {Headers, Response}} = httpc_aws:get("ec2","/?Action=DescribeTags&Version=2015-10-01").
```

To configure credentials, invoke ``httpc_aws:set_credentials/2``:

```erlang
application:start(httpc_aws).

httpc_aws:set_credentials("AKIDEXAMPLE", "wJalrXUtnFEMI/K7MDENG+bPxRfiCYEXAMPLEKEY"),

RequestHeaders = [{"Content-Type", "application/x-amz-json-1.0"},
                  {"X-Amz-Target", "DynamoDB_20120810.ListTables"}],

{ok, {Headers, Response}} = httpc_aws:post("dynamodb", "/",
                                           "{\"Limit\": 20}",
                                           RequestHeaders).
```

## Build

```bash
$ bin/rebar3 compile
```

## Test

```bash
$ bin/rebar3 eunit && bin/rebar3 eunit
$ bin/rebar3 dialyzer
```

## License

BSD 3-Clause License