User manual of API gateway Android SDK

Last Updated: Jan 08, 2018

User manual of API gateway Android SDK

1. Preface

This document describes how to use the Android SDK for API gateway products.

This SDK can be used by mobile terminals to call private and public APIs already connected to the API gateway, and APIs currently for sale in the API marketplace.

2. Install API gateway Android SDK

2.1 Download SDK

Find the SDK and Samples menu on the left side of the API gateway console and click the link to the SDK download page.

Follow the prompts on the page to View User Manual or Download SDK. Note the difference between code samples and SDKs. Code Samples are used for reference by users with no intentions of using an SDK to call APIs. SDK makes it easier for users to call APIs.

Click Download SDK. Your browser opens the Alibaba Cloud mobile service SDK download page. On the download page, select “API gateway” and then click “Download Android Version”. Follow the prompts on the page to download the API gateway Android SDK.

2.2 Use the SDK during the project

Decompress the SDK archive and place the decompressed “*.jar” file in the directory specified for the Android project.


Place “alicloud-android-apigateway-sdk-version.jar” in the application project’s “libs” directory and add the following content to the project’s “build.gradle” file:

  1. dependencies {
  2. // Add API gateway Android dependencies, find the jar file in the downloaded archive and copy it to the current project"s libs directory. Enter the actual file name, and "version" is only a placeholder.
  3. compile files("libs/alicloud-android-apigateway-sdk-version.jar")
  4. // Add third-party HTTP request for implementation. We recommend version 3.4.1 or later.
  5. compile "com.squareup.okhttp3:okhttp:3.4.1"
  6. }

3. Application initialization

Before using the Android SDK to call an API, you must provide some initialization configurations for the SDK context, such as permission statements, transfer application context, and access control.

3.1 Permission statements

In “AndroidManifest.xml”, add the following content:

  1. <uses-permission android:name="android.permission.INTERNET" />

3.2 AppKey configuration

3.2.1 Unsecure AppKey and AppSecret configuration

In the development and testing stage, we strongly recommend that you use an unsecure method to configure the AppKey and AppSecret. We strongly recommend you create a new mobile application on the console, instead of using an AppKey shared with another application on the terminal.

On the console, retrieve the application AppKey and AppSecret. Then, add the following content in “AndroidManifest.xml”:

  1. <application>
  2. <meta-data android:name="" android:value="appKey" />
  3. <meta-data android:name="" android:value="appSecret" />
  4. </application>
3.2.2 Secure AppKey and AppSecret storage

Use the “Mobile Security” product provided by Alibaba Cloud. Click here for product information.

Use the “Secure Storage” function to securely store the AppKey and AppSecret on the mobile application terminal. Click here to view the user manual. According to the preceding User Manual, connect to the Mobile Security product and save the AppKey and AppSecret required for API gateway in a secure image.

You must follow the preceding instructions and use the Mobile Security SDK to correctly place the secure image. API gateway automatically extracts the required data from the secure image.

3.3 SDK Initialization

During application initialization, add the SDK initialization code. Here we take MainActivity as an example:

  1. package ...;
  2. import ...;
  3. public class MainActivity extends AppCompatActivity {
  4. @Override
  5. protected void onCreate() {
  6. super.onCreate();
  7. // Initialize the API gateway SDK
  8. initgatewaySdk();
  9. }
  10. private void initgatewaySdk() {
  11. // Initialize API gateway
  12. ApigatewayClient.init(getApplicationContext(), false);
  13. }
  14. }

Note that, if the AppKey and AppSecret required by the SDK have been securely stored using the Mobile Security service, you must use the following initialization code:

  1. ApigatewayClient.init(getApplicationContext(), true);

4. SDK usage example

4.1 Call an API

Synchronous call:

Here, we use the Alibaba Cloud SMS Service on the cloud marketplace as an example.

  1. // Get the service
  2. RpcService rpcService = ApigatewayClient.getRpcService();
  3. ApiRequest apiRequest = new ApiRequest();
  4. // Set the request address, path, and method
  5. apiRequest.setAddress("");
  6. apiRequest.setPath("/singleSendSms");
  7. apiRequest.setMethod(HttpMethod.GET);
  8. // Based on the documentation, set the Query parameters including Header, Form-format Body, and Binary-format Body
  9. apiRequest.addQuery("ParamString", "demo");
  10. apiRequest.addQuery("RecNum", "demo");
  11. apiRequest.addQuery("SignName", "demo");
  12. apiRequest.addQuery("TemplateCode", "demo");
  13. // Set the time-out value and other settings
  14. apiRequest.setTime-out(3000);
  15. try {
  16. ApiResponse apiResponse =;
  17. // Process apiResponse; the common method is shown as follows
  18. // RequestId
  19. // apiResponse.getRequestId();
  20. // Code
  21. // apiResponse.getCode();
  22. // ErrorMessage
  23. // apiResponse.getErrorMessage();
  24. // Response Content
  25. // apiResponse.getStringBody();
  26. // Response Headers
  27. // apiResponse.getHeaders();
  28. } catch (ApiInvokeException e) {
  29. // Process exceptions
  30. }

Asynchronous callback:

Here, we use ID Card Recognition on the cloud marketplace as an example.

  1. // Get the service
  2. RpcService rpcService = ApigatewayClient.getRpcService();
  3. final ApiRequest apiRequest = new ApiRequest();
  4. // Set the request address, path, and method
  5. apiRequest.setAddress("");
  6. apiRequest.setPath("/rest/160601/ocr/ocr_idcard.json");
  7. apiRequest.setMethod(HttpMethod.POST);
  8. // Based on the documentation, set the Binary-format Body including Query and Header parameters, and Form-format Body
  9. apiRequest.setStringBody("JSON-format parameter");
  10. // Set the supported self-signed and other format certificates. If the server certificate is valid, do not set this value. This is only used for development and testing, or in unconventional scenarios.
  11. apiRequest.setTrustServerCertificate(true);
  12. // Set the time-out value
  13. apiRequest.setTime-out(10000);
  14., new ApiResponseCallback() {
  15. @Override
  16. public void onSuccess(ApiResponse apiResponse) {
  17. // Process apiResponse
  18. }
  19. @Override
  20. public void onException(ApiInvokeException e) {
  21. // Process exceptions
  22. }
  23. });
Thank you! We've received your feedback.