A lightweight Java client library for calling APIs exposed by the Amazon Web Services API Gateway. The API Gateway can route client calls to invoke AWS Lambda functions or any publicly addressable REST service regardless of where it is hosted. This library is ideally suited for integrating services exposed by the API Gateway into a wide range of applications, from mobile to new or existing server, middleware and cluster computing solutions.

This library provides the following AWS API Gateway support:

Simplified API execution using {@link io.onetapbeyond.aws.gateway.executor.AWSTask AWSTask}, no boilerplate {@link java.net} code required.
Fine grained access control to the API Gateway with support for gateway API keys.
Distributed cluster environment support through automatic {@link io.onetapbeyond.aws.gateway.executor.AWSTask AWSTask} and {@link io.onetapbeyond.aws.gateway.executor.AWSResult AWSResult} serialization.

When working with this library the basic usage pattern involves two steps:

Step 1. Identify an API on AWS API Gateway

An application identifies an API on the AWS API Gateway that it intends to use by creating an instance of {@link io.onetapbeyond.aws.gateway.executor.AWSGateway AWSGateway}. The basic builder pattern for creating instances of {@link io.onetapbeyond.aws.gateway.executor.AWSGateway AWSGateway} is as follows:

 
AWSGateway gateway = AWS.Gateway(api-id).region(api-region).stage(api-stage).build();

See the documentation on the {@link io.onetapbeyond.aws.gateway.executor.AWSGateway AWSGateway} class for builder details. Note, if an application needs to integrate with more than one API on the AWS API Gateway then it should create an {@link io.onetapbeyond.aws.gateway.executor.AWSGateway AWSGateway} instance per API.

Step 2. Make API calls on AWS API Gateway

An application can create any number of executable {@link io.onetapbeyond.aws.gateway.executor.AWSTask AWSTask} where each task represents an API call on the AWS API Gateway. The basic builder pattern for creating instances of {@link io.onetapbeyond.aws.gateway.executor.AWSTask AWSTask} is as follows:

 
AWSTask aTask = AWS.Task(gateway).resource(api-endpoint).get();

See the documentation on the {@link io.onetapbeyond.aws.gateway.executor.AWSTask AWSTask} class for builder details.

Example Usage

The following code snippet demonstrates the creation of an {@link io.onetapbeyond.aws.gateway.executor.AWSGateway AWSGateway} targeting the beta release of a fictitious Echo API. The API is identified by echo-api-key, and maintained in the us-west-2 region by the AWS API Gateway:

AWSGateway gateway = AWS.Gateway(echo-api-key).region(AWS.Region.OREGON).stage("beta").build();

Once your application has an instance of {@link io.onetapbeyond.aws.gateway.executor.AWSGateway AWSGateway} you can start to create instances of {@link io.onetapbeyond.aws.gateway.executor.AWSTask AWSTask} in order to make calls on the API. For example, the following code snippet demonstrates how to define a simple HTTP GET call on the API's echo resource endpoint:

AWSTask aTask = AWS.Task(gateway).resource("/echo").get();

To pass JSON data on an API call simply specify the data when building the {@link io.onetapbeyond.aws.gateway.executor.AWSTask AWSTask} instance:

Map data = new HashMap();
data.put("hello", "world");
AWSTask aTask = AWS.Task(gateway).resource("/echo").input(data).post();

Finally, to exeucte an {@link io.onetapbeyond.aws.gateway.executor.AWSTask AWSTask} call the {@link io.onetapbeyond.aws.gateway.executor.AWSTask#execute execute} method as follows:

AWSResult aResult = aTask.execute();

When the task execution completes the API call status, result data and/or error details are available on the {@link io.onetapbeyond.aws.gateway.executor.AWSResult AWSResult} returned by the {@link io.onetapbeyond.aws.gateway.executor.AWSTask#execute execute} method.