Use a Java SDK generated by API Gateway for a REST API - Amazon API Gateway

Use a Java SDK generated by API Gateway for a REST API

In this section, we outline the steps to use a Java SDK generated by API Gateway for a REST API, by using the Simple Calculator API as an example. Before proceeding, you must complete the steps in Generate SDKs for an API using the API Gateway console.

To install and use a Java SDK generated by API Gateway
  1. Extract the contents of the API Gateway-generated .zip file that you downloaded earlier.

  2. Download and install Apache Maven (must be version 3.5 or later).

  3. Download and install JDK 8.

  4. Set the JAVA_HOME environment variable.

  5. Go to the unzipped SDK folder where the pom.xml file is located. This folder is generated-code by default. Run the mvn install command to install the compiled artifact files to your local Maven repository. This creates a target folder containing the compiled SDK library.

  6. Type the following command in an empty directory to create a client project stub to call the API using the installed SDK library.

    mvn -B archetype:generate \ -DarchetypeGroupdId=org.apache.maven.archetypes \ \ -DartifactId=SimpleCalc-sdkClient

    The separator \ in the preceding command is included for readability. The whole command should be on a single line without the separator.

    This command creates an application stub. The application stub contains a pom.xml file and an src folder under the project's root directory (SimpleCalc-sdkClient in the preceding command). Initially, there are two source files: src/main/java/{package-path}/ and src/test/java/{package-path}/ In this example, {package-path} is examples/aws/apig/simpleCalc/sdk/app. This package path is derived from the DarchetypeGroupdId value. You can use the file as a template for your client application, and you can add others in the same folder if needed. You can use the file as a unit test template for your application, and you can add other test code files to the same test folder as needed.

  7. Update the package dependencies in the generated pom.xml file to the following, substituting your project's groupId, artifactId, version, and name properties, if necessary:

    <project xmlns="" xmlns:xsi="" xsi:schemaLocation=""> <modelVersion>4.0.0</modelVersion> <groupId></groupId> <artifactId>SimpleCalc-sdkClient</artifactId> <packaging>jar</packaging> <version>1.0-SNAPSHOT</version> <name>SimpleCalc-sdkClient</name> <url></url> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-java-sdk-core</artifactId> <version>1.11.94</version> </dependency> <dependency> <groupId>my-apig-api-examples</groupId> <artifactId>simple-calc-sdk</artifactId> <version>1.0.0</version> </dependency> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>4.12</version> <scope>test</scope> </dependency> <dependency> <groupId>commons-io</groupId> <artifactId>commons-io</artifactId> <version>2.5</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.5.1</version> <configuration> <source>1.8</source> <target>1.8</target> </configuration> </plugin> </plugins> </build> </project>

    When a newer version of dependent artifact of aws-java-sdk-core is incompatible with the version specified above (1.11.94), you must update the <version> tag to the new version.

  8. Next, we show how to call the API using the SDK by calling the getABOp(GetABOpRequest req), getApiRoot(GetApiRootRequest req), and postApiRoot(PostApiRootRequest req) methods of the SDK. These methods correspond to the GET /{a}/{b}/{op}, GET /?a={x}&b={y}&op={operator}, and POST / methods, with a payload of {"a": x, "b": y, "op": "operator"} API requests, respectively.

    Update the file as follows:

    package; import; import com.amazonaws.opensdk.config.ConnectionConfiguration; import com.amazonaws.opensdk.config.TimeoutConfiguration; import*; import*; import*; public class App { SimpleCalcSdk sdkClient; public App() { initSdk(); } // The configuration settings are for illustration purposes and may not be a recommended best practice. private void initSdk() { sdkClient = SimpleCalcSdk.builder() .connectionConfiguration( new ConnectionConfiguration() .maxConnections(100) .connectionMaxIdleMillis(1000)) .timeoutConfiguration( new TimeoutConfiguration() .httpRequestTimeout(3000) .totalExecutionTimeout(10000) .socketTimeout(2000)) .build(); } // Calling shutdown is not necessary unless you want to exert explicit control of this resource. public void shutdown() { sdkClient.shutdown(); } // GetABOpResult getABOp(GetABOpRequest getABOpRequest) public Output getResultWithPathParameters(String x, String y, String operator) { operator = operator.equals("+") ? "add" : operator; operator = operator.equals("/") ? "div" : operator; GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator)); return abopResult.getResult().getOutput(); } public Output getResultWithQueryParameters(String a, String b, String op) { GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op)); return rootResult.getResult().getOutput(); } public Output getResultByPostInputBody(Double x, Double y, String o) { PostApiRootResult postResult = sdkClient.postApiRoot( new PostApiRootRequest().input(new Input().a(x).b(y).op(o))); return postResult.getResult().getOutput(); } public static void main( String[] args ) { System.out.println( "Simple calc" ); // to begin App calc = new App(); // call the SimpleCalc API Output res = calc.getResultWithPathParameters("1", "2", "-"); System.out.printf("GET /1/2/-: %s\n", res.getC()); // Use the type query parameter res = calc.getResultWithQueryParameters("1", "2", "+"); System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC()); // Call POST with an Input body. res = calc.getResultByPostInputBody(1.0, 2.0, "*"); System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC()); } }

    In the preceding example, the configuration settings used to instantiate the SDK client are for illustration purposes and are not necessarily recommended best practice. Also, calling sdkClient.shutdown() is optional, especially if you need precise control on when to free up resources.

We have shown the essential patterns to call an API using a Java SDK. You can extend the instructions to calling other API methods.