DataWorks:Call an API

Prerequisites: Three essential elements

Before you call any Data Service API, you must meet three prerequisites:

The relationship between these three elements: the API is the "door," the app is the "ID card," and authorization is the "pass." You can only pass through the door if you present both a valid ID card and the corresponding pass.

Create an app (app identity)

An app serves as a container for API-calling credentials. Each app has an independent set of authentication information (AppKey, AppSecret, and AppCode), equivalent to an account and password.

Automatically created default app

When you publish an API in DataWorks for the first time, the system automatically creates an app with the same name as the workspace in API Gateway and authorizes all APIs in that workspace to this default app. This means that:

• Workspace members can use the default app's credentials to call APIs without additional authorization.

• The authentication information of the default app can be viewed on the Call APIs page of the Data Service console.

Manually create an app

To isolate traffic or differentiate permissions for different callers, create a new app in the API Gateway console:

1. Log on to the API Gateway console.

2. In the left-side navigation pane, choose Application Management.

3. Click Create Application and enter the app name and description.

4. After the app is created, the system generates a set of AppKey, AppSecret, and AppCode for the app.

Authorization process

Authorization grants an app permission to call a specific API. Only an authorized app can successfully call the corresponding API using its credentials.

Grant access to other accounts

To make an API available to workspaces under other Alibaba Cloud accounts, perform cross-account authorization:

1. Log on to the DataWorks console. In the target region, click Data Analysis and Service > DataService Studio in the left-side navigation pane. Select a workspace from the drop-down list and click Go to DataService Studio.

2. Go to the Data Services page, click Service Management in the top menu bar, and go to the Manage APIs page.

3. On the Published APIs tab, find the target API and click Authorization in the Actions column.

4. In the API Authorization dialog, configure the following parameters:

   

   Parameter	Description
   API Name	The name of the API to be authorized. This value cannot be modified.
   Alibaba Cloud Account ID to Authorize	The Alibaba Cloud account ID that needs to be granted the permission to call this API. You can view the account ID on the page.
   Authorized Workspace	Select the workspace under the target Alibaba Cloud account.
   Authorization Validity Period	Select the authorization validity period (see details below).

5. Click Confirm to complete the authorization.

Authorization validity period

The authorization validity period determines how long the authorized party can call the API:

View authorized and granted APIs

On the Manage APIs page, you can view the authorization status from two perspectives:

View APIs authorized to you (which APIs am I authorized to use)

Click the Authorized to Use tab to view all APIs that other accounts have authorized to you. On this page, you can:

• Click Test to test an authorized API online. For more information, see Test an API.

• Click Delete to voluntarily give up the calling authorization for an API.

View APIs you have authorized to others (which APIs have I authorized to others)

Click the Authorize Others to Use tab to view the APIs you have authorized to other workspaces. On this page, you can:

• Click Test to test an authorized API online.

• Click Manage to revoke or modify the authorization for a specific workspace.

Three authorization scenarios

API authorization granularity varies depending on team size and security requirements. The following three scenarios cover the most common approaches.

Scenario 1: Same workspace, sharing one app

Scenario description: All members within the same DataWorks workspace share the default app that was automatically created for the workspace to call APIs.

Applicable situation: Small team with high mutual trust; no need to differentiate call traffic by individual member; quick start with minimal configuration.

How it works: When an API is published, DataWorks automatically creates an app with the same name as the workspace and authorizes all APIs in the workspace to this app. All workspace members share the same AppKey, AppSecret, and AppCode.

Advantage: Zero configuration, ready to use out of the box. Disadvantage: Cannot identify which specific member initiated a call; if credentials are leaked, the entire workspace is affected.

Scenario 2: Each RAM user uses an independent app

Scenario description: Each RAM user (sub-account) in the organization creates an independent app in API Gateway and is individually authorized to call APIs.

Applicable situation: Need to precisely track each user's API calling behavior; need to set different throttling policies for different users; high security and compliance requirements that mandate per-user credentials.

How it works: Each RAM user logs on to the API Gateway console and creates their own app; the API administrator authorizes the API to each user's app individually; each user calls the API using their own app's credentials.

Advantage: Calling behavior is traceable to individuals, strong security isolation, and minimal impact from credential leakage. Disadvantage: Higher management overhead; each new user requires app creation and authorization configuration.

Scenario 3: Multiple RAM users grouped, each group sharing one app

Scenario description: Multiple RAM users are divided into groups by business function or team, and members within each group share the same app to call APIs.

Applicable situation: Large team organized by department or project; need to differentiate call traffic by business line without requiring per-user tracking; balancing management cost and security.

How it works: Create a corresponding number of apps for each business group; the API administrator authorizes the API to each group's app; members within a group share their group app's credentials.

Advantage: Moderate management granularity that distinguishes business sources without excessive overhead. Disadvantage: Cannot further differentiate members within the same group.

Scenario selection recommendations

Three types of credentials: Avoid confusion

Data Service uses three distinct types of authentication credentials with different purposes, sources, and usage scenarios. Make sure you distinguish them:

Quick summary: AccessKey is for "connecting to data sources," AppKey is for "calling APIs," and RAM is for "accessing the console." Each serves a different purpose and cannot replace the others.

Confusion 1: "My API call returns 403, but I have RAM administrator permissions" — RAM permissions control DataWorks console operations, not API calling permissions. API calling permissions are controlled by app authorization. Even if you are a RAM administrator, you still need an authorized app's AppKey/AppSecret to call an API.

Confusion 2: "Is the AccessKey configured for the data source the same as the AppKey for API calls?" — No. AccessKey is used by Data Service to connect to backend data sources; AppKey is used by callers to call APIs. They are completely independent.

Confusion 3: What should I enter in the "Alibaba Cloud Account ID" field on the authorization page? — The authorization page requires the Alibaba Cloud account ID (a numeric value), not a RAM username or login email. To obtain it, log on to the Account Management page and view the account ID in the security settings.

Authentication method comparison

API Gateway supports two authentication methods. Data Service adds "Alibaba Cloud APP authentication" to APIs in the workspace by default. Choose a method based on your security requirements.

Simple authentication (AppCode)

Add the AppCode to the HTTP request header to complete authentication. No signature calculation is required.

Request example:

GET /api/v1/users?name=test HTTP/1.1
Host: your-api-endpoint.cn-shanghai.alicloudapi.com
Authorization: APPCODE 3f963a8e1cd7492bbd8a5e2e5e4c****

Signature authentication (AppKey + AppSecret)

The caller uses AppSecret to compute an HMAC-SHA256 signature over the request content and adds the AppKey and signature to the request header. API Gateway recalculates the signature using the same AppSecret and compares it to verify the caller's identity.

Request example (header section):

X-Ca-Key: 12345678
X-Ca-Signature: BASE64_ENCODED_SIGNATURE
X-Ca-Timestamp: 1741593600000
X-Ca-Nonce: unique-uuid-string
X-Ca-Signature-Headers: X-Ca-Key,X-Ca-Nonce,X-Ca-Timestamp

Comparison of the two methods

Signature algorithm details

Signature authentication is based on the HMAC-SHA256 algorithm. The core process is as follows:

Signature process overview

1. Construct the canonicalized request string (StringToSign): Concatenate the HTTP method (GET/POST), Accept header, Content-MD5 (MD5 value of the request body), Content-Type, Date, custom headers involved in the signature (X-Ca-*, sorted alphabetically), and the canonicalized URL (path + sorted query parameters) in sequence.

2. Calculate the signature using HMAC-SHA256: Signature = Base64(HMAC-SHA256(AppSecret, StringToSign))

3. Add the signature information to the request header: This includes X-Ca-Key (AppKey), X-Ca-Signature (signature value), X-Ca-Timestamp (millisecond-level timestamp), X-Ca-Nonce (UUID for anti-replay), and X-Ca-Signature-Headers (list of headers involved in the signature).

Key considerations

The following details are common sources of signature errors:

• Parameter sorting: URL query parameters and signature headers must be sorted by key in alphabetical order (ASCII order).

• URL encoding: Special characters in parameter values (spaces, Chinese characters, etc.) must be URL-encoded.

• Line separator: Lines in StringToSign must be separated by \n (LF). Do not use \r\n (CRLF).

• Empty value handling: When there is no body, Content-MD5 is an empty string (not null). When headers such as Accept do not exist, use an empty string as well.

• Timestamp precision: X-Ca-Timestamp is a millisecond-level timestamp. The time difference between the client and the server must not exceed 15 minutes.

• Nonce uniqueness: A unique UUID must be generated for each request as X-Ca-Nonce. Reusing a nonce triggers replay attack interception.

View authentication credentials

After you create an app and obtain authorization, retrieve the AppKey, AppSecret, or AppCode to make API calls.

View credentials from the Data Service console

1. Log on to the DataWorks console. In the target region, click Data Analysis and Service > DataService Studio in the left-side navigation pane. Select a workspace from the drop-down list and click Go to DataService Studio.

2. On the Data Service page, click Service Management in the top menu bar.

3. In the left-side navigation pane, click Call APIs.

4. On the Call APIs page, you can view and copy the following authentication information: AppKey (unique app identifier), AppSecret (used for signature authentication; keep it secure), and AppCode (used for simple authentication).

View credentials from the API Gateway console: Log on to the API Gateway console, find the target app in Application Management, and go to the app details page to view the AppKey, AppSecret, and AppCode.

Call APIs using the API Gateway SDK

API Gateway provides SDKs for mainstream programming languages with built-in signature algorithm implementations. You only need to provide the AppKey and AppSecret. For more information, see Call an API and SDK download and usage.

Supported SDK languages

Advantages of using the SDK

Compared to manually constructing HTTP requests, the SDK offers these advantages:

• Automatic signing: The SDK implements the HMAC-SHA256 signature algorithm, so developers do not need to handle signing details.

• Automatic retry: Some SDKs include built-in retry mechanisms for network exceptions.

• Parameter validation: The SDK validates parameters before sending requests.

• Performance optimization: SDKs typically use connection pooling and HTTP/2 to improve network performance.

Quick integration example (Java)

The following example shows how to call a Data Service API using the API Gateway Java SDK:

// 1. Add Maven dependency
// <dependency>
//     <groupId>com.aliyun.api.gateway</groupId>
//     <artifactId>sdk-core-java</artifactId>
//     <version>latest version</version>
// </dependency>

// 2. Initialize the client
HttpClientBuilderParams params = new HttpClientBuilderParams();
params.setAppKey("your_app_key");
params.setAppSecret("your_app_secret");

ApacheHttpClient client = new ApacheHttpClient(params);

// 3. Construct the request
IoTApiRequest request = new IoTApiRequest();
request.setDomain("your-api-endpoint.cn-shanghai.alicloudapi.com");
request.setPath("/api/v1/query");
request.setHttpMethod("GET");
request.putQueryParam("pageSize", "10");
request.putQueryParam("pageNum", "1");

// 4. Execute the call
ApiResponse response = client.execute(request);
System.out.println("Response: " + response.getBody());

Quick integration example (Python)

# 1. Install the SDK
# pip install aliyun-api-gateway-sdk

# 2. Call the API
from com.alibaba.cloudapi.sdk.client import DefaultClient
from com.alibaba.cloudapi.sdk.model import HttpClientBuilderParams

params = HttpClientBuilderParams()
params.app_key = "your_app_key"
params.app_secret = "your_app_secret"
params.host = "your-api-endpoint.cn-shanghai.alicloudapi.com"

client = DefaultClient(params)
response = client.get(
    path="/api/v1/query",
    query_params={"pageSize": "10", "pageNum": "1"},
    headers={"Accept": "application/json"}
)

print(f"Status: {response.status_code}")
print(f"Body: {response.content}")

Complete call process summary

The complete process from API publishing to a successful call: The API developer develops, tests, and publishes the API to API Gateway, which automatically creates a default app and authorization. For cross-account sharing, the developer manually authorizes the target account. The API caller creates an app or uses the default app, obtains credentials (AppKey/AppSecret/AppCode), chooses an authentication method (AppCode for simple authentication or AppKey + AppSecret for signature authentication), and calls the API through the SDK or HTTP. After API Gateway verifies the identity, Data Service executes the query and returns the results.

References

• Publish an API: Learn how to publish an API to API Gateway.

• Authorize an API: Learn about authorization operations and managing APIs authorized to others.

• Test an API: Test published or authorized APIs on the Service Management page.