If an Alibaba Cloud product does not provide an SDK for its APIs, you can use the generic calling method (CommonRequest) to call the product APIs. By using the CommonRequest calling method, you can call any API.

Benefits

CommonRequest has the following benefits:

  1. Lightweight: You only need to download the core package. You do not need to download and then install an SDK.
  2. Easy to use: You can call the newly released API operations without updating the SDK.
  3. Fast iteration.

Use CommonRequest to call an API operation

The APIs of Alibaba Cloud services use two styles: RPC and RESTful. The method of making a CommonRequest request varies based on the API style.

In most cases, an API uses the RPC style if its API operations include the Action parameter. An API uses the RESTful style if its API operations include the PathPattern parameter. Typically, all API operations of a service uses the same API style. Each service API only supports one style. If you pass the wrong identifier, another API operation may be called or the ApiNotFound error may be returned.

To make a CommonRequest request, you must obtain the values for the following parameters. You can obtain the values of these parameters from the API reference in Documentation. You can also obtain the parameter values of an API from OpenAPI Explorer.

  • Domain: the endpoint of a service.
  • Version: the version of the API, in the format of YYYY-MM-DD.

    You can find the API version of a service in the Common Parameters section of the API reference.

  • Operation information: the name of the API operation that you want to call.
    • If you want to call an RPC API (the APIs of most Alibaba Cloud services are RPC APIs, such as ECS and ApsaraDB for RDS), you must obtain the value of the Action parameter and specify the value in the request.ApiName = "<Action>".

      For example, to use the CommonRequest method to call the RunInstances operation, you must specify the operation name by using request.ApiName = "RunInstances".

    • If you want to call a RESTful API, such as the API of Container Service, you must obtain the value of the PathPattern parameter, and specify the RESTful path in the request.PathPattern = "<PathPattern>" format.

      For example, the PathPattern parameter of the API operation that is used to query all cluster instances is set to /clusters. When you initiate a CommonRequest request, you must specify the RESTful path in the request.PathPattern = "/clusters" format.

Example: Call an RPC API

The following code shows how to use the CommonRequest calling method to call the DescribeInstanceStatus API:
using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Exceptions;
using Aliyun.Acs.Core.Profile;

class Sample
{
    static void Main(string[] args)
    {
        // Construct a client instance for initializing requests
        IClientProfile profile = DefaultProfile.GetProfile(
            "<your-region-id>",
            "<your-access-key-id>",
            "<your-access-key-secret>")
        DefaultAcsClient client = new DefaultAcsClient(profile);

        try
        {
            // Construct a request
            CommonRequest request = new CommonRequest();
            request.Domain = "ecs.aliyuncs.com";
            request.Version = "2014-05-26";

            // Because the API is an RPC API, you must specify the value of the ApiName (Action) field.
            request.Action = "DescribeInstanceStatus";
            request.AddQueryParameters("PageNumber", "1");
            request.AddQueryParameters("PageSize", "30");

            // Initiate the request and obtain the response
            CommonResponse response = client.GetCommonResponse(request);
            System.Console.WriteLine(response.Data);
        }
        catch (ServerException ex)
        {
            System.Console.WriteLine(ex.ToString());
        }
        catch (ClientException ex)
        {
            System.Console.WriteLine(ex.ToString());
        }
    }
}

Example: Call a RESTful API

The following code shows how to use the CommonRequest calling method to call the GetClusterList API:
using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Exceptions;
using Aliyun.Acs.Core.Profile;

class Sample
{
    static void Main(string[] args)
    {
        // Construct a client instance for initializing requests
        IClientProfile profile = DefaultProfile.GetProfile(
            "<your-region-id>",
            "<your-access-key-id>",
            "<your-access-key-secret>");
        DefaultAcsClient client = new DefaultAcsClient(profile);

        try
        {
            // Construct a request
            CommonRequest request = new CommonRequest();
            request.Domain = "cs.aliyuncs.com";
            request.Version = "2015-12-15";

            // Because the API is a RESTful API, you must specify the value of the UriPattern field.
            request.UriPattern = "/clusters";

            // Initiate the request and obtain the response
            CommonResponse response = client.GetCommonResponse(request);
            System.Console.WriteLine(response.Data);
        }
        catch (ServerException ex)
        {
            System.Console.WriteLine(ex.ToString());
        }
        catch (ClientException ex)
        {
            System.Console.WriteLine(ex.ToString());
        }
    }
}