aws-gateway-executor: A Java repository from onetapbeyond

AWS API Gateway Executor (AGE)

A lightweight Java client library for calling APIs exposed by the Amazon Web Service 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.

Gradle Dependency

compile 'io.onetapbeyond:aws-gateway-executor:1.2'

Maven Dependency

<dependency>
  <groupId>io.onetapbeyond</groupId>
  <artifactId>aws-gateway-executor</artifactId>
  <version>1.2</version>
</dependency>

AWS API Gateway Integration

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

Usage

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

####Step 1. Identify an API on the AWS API Gateway

An application identifies an API on the AWS API Gateway by creating an instance of AWSGateway. The basic builder pattern for creating instances of AWSGateway is as follows:

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

See the documentation on the 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 AWSGateway instance per API.

Step 2. Make API calls on the AWS API Gateway

An application can create any number of executable AWSTask where each task represents an API call on the AWS API Gateway. The basic builder pattern for creating instances of AWSTask is as follows:

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

See the documentation on the AWSTask class for builder details.

Example Usage

The following code snippet demonstrates the creation of an 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)
                        .stage("beta")
                        .region(AWS.Region.OREGON)
                        .build();

Once your application has an instance of AWSGateway you can start to create instances of 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 input data on an API call specify the data when building the AWSTask instance. For example, here we define a HTTP POST call passing JSON input data on the API's /echo/greeting resource endpoint:

Map data = new HashMap();
data.put("message", "Hello, World!");

AWSTask aTask = AWS.Task(gateway)
                   .resource("/echo/greeting")
                   .input(data)
                   .post();

Finally, to execute any AWSTask simply call the 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 AWSResult returned by the aTask.execute() method.

License

See the LICENSE file for license rights and limitations (Apache License 2.0).

onetapbeyond/aws-gateway-executor