SDK usage guide

How it works

The SDK is a language binding for ADA Open APIs. A client instance holds credentials and region configuration. Method calls map to specific API operations, and request signing is handled internally by the SDK.

SDK versions correspond to API versions. Breaking changes are released under a new API version, and the SDK upgrades its major version accordingly. Upgrades within the same major version remain backward-compatible.

Errors are returned in two categories. Signature, authentication, parameter, and quota errors are thrown directly, and you must fix them before retrying. Throttling and transient server errors are retried by the SDK with a backoff strategy and are thrown only after all retries are exhausted.

Usage notes

The languages, package names, and versions supported by the SDK are subject to the information published on the OpenAPI portal. The portal also provides call examples for each language, which you can use alongside the integration procedure below.

For runtime environments where no SDK is available, send HTTPS requests directly according to the signature specification. For more information, see the API overview and authentication topics.

Install and initialize the client

The client holds long-lived credentials. The initialization method determines the exposure scope of the credentials. Decide on the credential source before you write code.

1. Install the SDK for the target language by using a package manager. The package name and version are subject to the information published on the OpenAPI portal.

2. Prepare credentials. For local development, read credentials from environment variables or a credential file, and add the credential file to the version control ignore list. When deploying on Alibaba Cloud, use an instance RAM role to avoid storing long-lived AccessKeys in the environment.

3. Specify the region. The region determines which set of resources to access and must match the region of the target resources.

4. Create a client instance and reuse it within the process. The client holds connection configurations, and creating a new instance for each call incurs unnecessary overhead.

The following example shows what client initialization looks like in Node.js. The package name and import path are placeholders. Use the actual values published on the OpenAPI portal.

import Client, { Config } from '<ada-sdk-package>'

const config: Config = {
  // Credentials are injected via environment variables and are not committed to the code repository
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID,
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET,
  regionId: 'cn-hangzhou',
}

// Reuse the client within the process
const client = new Client(config)

Read and synchronize resource lists

List calls return paginated results. Missing pages lead to incomplete lists — an issue that does not surface in test environments with small data volumes.

1. Explicitly set the page size when you call a list method. Do not rely on the default value.

2. Loop through pages until the number of returned records is less than the page size. If you use the total count field as the termination condition, be aware that additions during pagination can change the total.

3. Use the source parameter to distinguish platform-built-in resources from user-created resources. When verifying user-created configurations, retrieve only the user-created portion.

4. Index the returned results by name for comparison with locally maintained configuration files.

For the specific filter parameters for agents and skills, see the Agent API and Skill Management API topics.

Submit write operations and read back to confirm

Write methods return an operation receipt rather than the complete object. A successful call does not guarantee that the persisted result matches expectations.

1. Call the read method first to obtain the current configuration and version number.

2. Construct the write request based on the read result and include the version verification parameter. Write operations use overwrite semantics — assembling a request from an empty object clears any fields that are not included.

3. Submit the write request and record the returned request ID. This ID is the basis for troubleshooting individual calls.

4. Call the read method again to read back the result and verify key fields and associations.

5. If you receive a version conflict error, re-read the resource and redo the modifications. Do not remove the version check and force the submission.

Handle call failures

Determine whether the error is retryable before you decide how to handle it. Repeatedly retrying non-retryable errors only consumes quota.

Report parameter and authentication errors directly without retrying. The error message contains the specific field or permission entry, which you can use to fix the request or the RAM policy.

Throttling and transient server errors are handled by the SDK's built-in backoff retry mechanism. You still need to set an overall timeout on the integration side to prevent calls from hanging indefinitely.

Insufficient quota is a business error, and retrying is ineffective. Raise an alert on the integration side for such errors so that an administrator can replenish the quota. For more information, see the usage and quota topic.

Sanitize exception messages before outputting them. Error stack traces may contain request parameters, and writing them directly to logs can leak credentials and business data.

Apply to production environments

Pin the SDK version in production environments. Perform upgrades through a change verification process — complete a full round of calls in a test environment before switching over.

Throttle batch operations on your own. The SDK is not aware of your overall request pattern. Intensive batch requests trigger throttling and may also affect other calls that use the same credentials.

Separate credentials by purpose. Use different RAM users for batch synchronization, read-only queries, and workflows that involve delete operations. This makes it easy to distinguish call sources from logs, and credential rotation for one purpose does not affect others.

Log request IDs in your integration system. Providing a request ID during troubleshooting allows you to locate a specific call directly, which is far more efficient than searching by time range.

FAQ

• Q: Can I reuse the client globally?

  A: Yes, and we recommend doing so. The client holds credentials and connection configurations. A single instance per process is sufficient for concurrent calls.

• Q: The SDK method names do not match the API names on the portal.

  A: The SDK adapts naming conventions to the target programming language. The mapping is defined by the API definitions in the SDK release. If you are unsure, search the SDK documentation by using the API name shown on the portal.

• Q: Will upgrading the SDK affect my existing integration?

  A: Upgrades within the same major version are backward compatible. A major version upgrade corresponds to an API version change. Before upgrading, review the changelog and verify the upgrade in a test environment.

• Q: Where should I store credentials?

  A: For local development, use environment variables or credential files that are added to the ignore list. For cloud deployment, use instance RAM roles. Do not commit credentials to code repositories, build artifacts, or logs.