This topic describes the differences between the generic calls and specialized calls that you can make by using Alibaba Cloud SDKs. This topic also describes the benefits and limits of generic calls and specialized calls in terms of package size and development experience to help you select an appropriate call method. Sample code is provided to facilitate your project development.
Generic calls
Generic calls refer to the requests that are initiated by using a common call method. To make a generic call, use the core module of an Alibaba Cloud SDK to construct an object of request parameters, call a common method to initiate a request, and then obtain the returned result in a common object.
Specialized calls
Specialized calls refer to the requests that are initiated by using a specific call method. The call method involves a specific service API and API definition. To make a specialized call, use an Alibaba Cloud SDK to automatically construct the request client, object of request parameters, and object of response parameters based on the metadata of the API operation that you want to call. You can easily specify the required parameters and obtain the returned result as prompted in an integrated development environment (IDE).
Select a call method
Generic calls
Benefits: The size of your code package is compact after SDKs are integrated. You need to deploy only several core dependency packages to call API operations of all services.
Limits: If you use this method to call API operations, you must check the API reference all the way and face the lack of auto-complete suggestions in an IDE. This may affect your user experience.
Specialized calls
Benefits: Compared with generic calls, specialized calls bring more convenience to the development process. When you use SDKs in an IDE, the IDE can provide a variety of suggestions, such as parameter names, methods, and data types.
Limits:
Specialized calls depend on service-specific SDKs. Some services may not provide SDKs.
If your application uses multiple Alibaba Cloud services, you must install multiple SDKs. This makes the size of your code package comparatively larger.
Alibaba Cloud SDK V1.0 for JavaScript supports only generic calls.
Sample code
The following sample code provides examples on how to make a generic call and a specialized call by using Alibaba Cloud SDK V2.0.
Make a generic call
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>tea-openapi</artifactId>
<version>0.2.8</version>
</dependency>package com.aliyun.sample;
import com.aliyun.tea.*;
public class Sample {
/**
* Use your AccessKey ID and AccessKey secret to initialize the client.
* @param accessKeyId
* @param accessKeySecret
* @return Client
* @throws Exception
*/
public static com.aliyun.teaopenapi.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
// Required. Specify your AccessKey ID.
.setAccessKeyId(accessKeyId)
// Required. Specify your AccessKey secret.
.setAccessKeySecret(accessKeySecret);
// Specify an endpoint. For more information, see endpoints at https://api.aliyun.com/product/Ecs.
config.endpoint = "ecs-cn-hangzhou.aliyuncs.com";
return new com.aliyun.teaopenapi.Client(config);
}
/**
* API-related parameters
* @return OpenApi.Params
*/
public static com.aliyun.teaopenapi.models.Params createApiInfo() throws Exception {
com.aliyun.teaopenapi.models.Params params = new com.aliyun.teaopenapi.models.Params()
// The operation that you want to perform.
.setAction("DescribeInstanceStatus")
// The version number of the operation.
.setVersion("2014-05-26")
// The protocol of the operation.
.setProtocol("HTTPS")
// The HTTP method of the operation.
.setMethod("POST")
.setAuthType("AK")
.setStyle("RPC")
// The URL of the operation.
.setPathname("/")
// The format of the request body.
.setReqBodyType("json")
// The format of the response body.
.setBodyType("json");
return params;
}
public static void main(String[] args_) throws Exception {
java.util.List<String> args = java.util.Arrays.asList(args_);
// Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured.
// If the project code is leaked, the AccessKey pair may be disclosed, which may compromise the security of resources within your account. The following sample code shows how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. The sample code is for reference only. We recommend that you use Security Token Service (STS), which provides higher security. For more information about authentication methods, see the "Configure credentials" topic in the documentation of Alibaba Cloud SDK V2.0 for Java.
com.aliyun.teaopenapi.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
com.aliyun.teaopenapi.models.Params params = Sample.createApiInfo();
// query params
java.util.Map<String, Object> queries = new java.util.HashMap<>();
queries.put("RegionId", "cn-hangzhou");
// runtime options
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
.setQuery(com.aliyun.openapiutil.Client.query(queries));
// If you copy and run the sample code, write your own code to display the return value of the operation.
// The return value is of the Map type. The return value contains the following three types of data: response body, response headers, and HTTP status code.
client.callApi(params, request, runtime);
}
}
You can use com.aliyun.teaopenapi to create the Client, Params, and OpenApiRequest objects and call the callApi method to obtain the value of OpenApiResponse. You can call all API operations that are available in OpenAPI Explorer in this way.
Make a specialized call
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>ecs20140526</artifactId>
<version>5.1.8</version>
</dependency>
package com.aliyun.sample;
import com.aliyun.tea.*;
public class Sample {
/**
* Use your AccessKey ID and AccessKey secret to initialize the client.
* @param accessKeyId
* @param accessKeySecret
* @return Client
* @throws Exception
*/
public static com.aliyun.ecs20140526.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
// Required. Specify your AccessKey ID.
.setAccessKeyId(accessKeyId)
// Required. Specify your AccessKey secret.
.setAccessKeySecret(accessKeySecret);
// Specify an endpoint. For more information, see endpoints at https://api.aliyun.com/product/Ecs.
config.endpoint = "ecs-cn-hangzhou.aliyuncs.com";
return new com.aliyun.ecs20140526.Client(config);
}
public static void main(String[] args_) throws Exception {
java.util.List<String> args = java.util.Arrays.asList(args_);
// Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are configured.
// If the project code is leaked, the AccessKey pair may be disclosed, which may compromise the security of resources within your account. The following sample code shows how to use environment variables to obtain an AccessKey pair and use the AccessKey pair to call API operations. The sample code is for reference only. We recommend that you use STS, which provides higher security. For more information about authentication methods, see the "Configure credentials" topic in the documentation of Alibaba Cloud SDK V2.0 for Java.
com.aliyun.ecs20140526.Client client = Sample.createClient(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
com.aliyun.ecs20140526.models.DescribeInstanceStatusRequest describeInstanceStatusRequest = new com.aliyun.ecs20140526.models.DescribeInstanceStatusRequest()
.setRegionId("cn-hangzhou");
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
try {
// If you copy and run the sample code, write your own code to display the return value of the operation.
client.describeInstanceStatusWithOptions(describeInstanceStatusRequest, runtime);
} catch (TeaException error) {
// Display the error based on your business requirements.
com.aliyun.teautil.Common.assertAsString(error.message);
} catch (Exception _error) {
TeaException error = new TeaException(_error.getMessage(), _error);
// Display the error based on your business requirements.
com.aliyun.teautil.Common.assertAsString(error.message);
}
}
}
The client object com.aliyun.ecs20140526.Client, the describeInstanceStatusWithOptions method, the request object com.aliyun.ecs20140526.models.DescribeInstanceStatusRequest, and the response object com.aliyun.ecs20140526.models.DescribeInstanceStatusResponse are automatically generated based on the definition of each API operation.