API testing, publishing, and version management

Test an API in development

Testing an API in development means testing on the Service Development page (the development environment). Before you test the API, you must first generate it in wizard mode or script mode, or register an existing service as an API. For more information, see Generate API overview or Register an external API service.

Procedure:

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. From the API list on the left, double-click the name of the API that you want to test to open its editing page.

3. On the API editing page, find and click the Test button to open the Test APIs dialog box.

4. In the left pane of the dialog box, enter a test value for each request parameter.

5. Click Start Test to trigger the API call.

View test results:

After the test is complete, you can view the following information in the right pane of the dialog box:

• Request Details: The complete request information for the API call, including the request path, headers, and body. Use this to verify that the request is structured correctly.

• Response Details: The response data from the API (the actual query result). Compare this with the expected result to verify that the API logic is correct.

• Response Duration: The end-to-end response latency of the API request. If the latency is high, consider optimizing the query logic or data source configuration.

If the test fails, carefully review the error message returned, make the necessary modifications, and retest.

Test a published API

Testing a published API means testing on the Service Management page (the production environment). This verifies the actual runtime behavior of the API after publishing. Before you perform this test, you must first publish the API.

Procedure:

1. On the Data Services page, click Service Management in the top navigation bar.

2. In the left-side navigation pane, click Test APIs.

3. From the drop-down list, select the API that you want to test, and make sure the request parameter values are fully configured.

4. Click Start Test, and view the Request Details and Response Details in the right pane.

Notes:

• The Test APIs page only provides online API testing functionality. It does not support updating the normal response example of an API.

• If Pagination for Return Results is configured for an API, whether the returned data is ordered depends on the behavior of the underlying data source. If you need sorting, you can configure a Sort field for the API in wizard mode, or add an ORDER BY clause to the SQL code in script mode.

Interpreting test results and optimization suggestions

A complete API test result consists of three parts. Understanding each part helps you quickly identify issues:

After the test results meet expectations, you can proceed to publish the API to API Gateway.

Prerequisites

Before you publish an API, ensure the following conditions are met:

• API Gateway is activated: Activate the service in the API Gateway console.

  Important

  Due to network architecture limitations between DataWorks and API Gateway, when you purchase an API Gateway instance, only traditional dedicated instances are supported for Instance Type. VPC-integrated instances are not supported.

• An API group is created: When published, the API is deployed to the corresponding group in API Gateway based on the workflow association. Ensure the workflow is correctly associated with an API Gateway group. You can check the group name by right-clicking Workflow > Change.

Publishing process

API publishing follows a three-step process: Submit → Approval → Publish:

Step 1: Submit the API

1. Go to the Data Services page. On the Service Development page, double-click the name of the API you want to publish from the API list to open its editing page.

2. Click the Submission button in the upper-right corner.

3. After the submission succeeds, the system automatically generates an API version (such as V1 or V2). You can view the version status in the Version panel that appears on the right.

Step 2: Request publishing and wait for approval

1. In the Version panel on the right, find the API version to be published, and click the Publish button.

2. Follow the on-screen instructions to enter the reason for the request, and click Requested Permissions to submit the publishing request.

3. If the workspace has an approval process configured, the publishing request must be approved in the approval center. The approver can view the request details and process the approval on the Approval Center > To Be Processed page.

4. After the approval is granted, the API status in the Version panel changes from To Be Requested to Can Be Published.

Step 3: Execute publishing

1. After the approval is granted, in the right-side navigation bar of the API editing page, click Version, and find the API version with the Can Be Published status.

2. Click the Publish button and wait until the system indicates that the publishing is successful.

3. After the API is published, DataWorks deploys it to the corresponding group in API Gateway based on the associated group of the workflow to which the API belongs.

Post-publishing verification

After publishing, you can verify and manage the API in the following ways:

• View in API Gateway: Log on to the API Gateway console. View the published API information in Manage APIs > Service List, and configure policies such as throttling and access control.

• Application calls: If the API is called by your own application, create an application in API Gateway, authorize the API to the application, and then use AppKey and AppSecret for encrypted signature-based calls. API Gateway also provides SDKs for mainstream programming languages. For more information, see Authorize and call an API. For SDK integration, see SDK integration.

• Protocol change: For a published API, on the Service Management > Published APIs tab, click More > Change Protocol for the corresponding API to modify the access protocol (for example, from HTTP to HTTPS). The protocol change takes effect immediately. However, if the original protocol is removed, API calls using that protocol will fail. Proceed with caution.

List on Alibaba Cloud API Marketplace (optional)

Alibaba Cloud API Marketplace covers categories such as finance, artificial intelligence, e-commerce, transportation and geography, life services, enterprise management, and public affairs. Thousands of API products are available for sale, making it a platform that helps you quickly monetize your data. Alibaba Cloud API Marketplace

After APIs generated or registered in Data Service are published to API Gateway, you can list them on Alibaba Cloud API Marketplace for sale with one click, helping enterprises monetize data value.

Prerequisites:

• Only enterprise identities are supported for registering on Alibaba Cloud API Marketplace.

• Before listing, you need to register on the Alibaba Cloud Marketplace as a service provider. For the process, see Register as a service provider.

Procedure:

1. Go to the Alibaba Cloud Service Provider Platform.

2. In the left-side navigation pane, click Commodity > Product Management.

3. Click Publish Product.

4. On the Access Information page, configure the parameters as instructed (including the product name, pricing strategy, and API binding) to complete the API listing process. For more information, see Instructions for listing API products.

View version history

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 Service Development page, double-click the name of the API you want to view from the API list to open its editing page.

3. Click the Version button on the right side of the page to open the version panel and view version information and details. The version panel displays all historical version information for the current API, including:

   Note

   Each version provides an API Details link in the Actions column. Click it to view the complete configuration information of that version, including request parameters, response parameters, and data source configuration.

   Column	Description
   API ID	The unique identifier of the current API.
   Version	The version number, which increments in submission order (V1, V2, V3, and so on).
   Submitted By	The user who submitted this version.
   Submitted At	The publish time of this version, accurate to the second.
   Status	Publish (the latest version currently in effect online) Can Be Published (a version that has passed testing and been submitted) Batch Synchronization (a historical old version)

Version comparison

After multiple iterations of an API, you may need to compare versions to understand the specific changes.

Procedure:

1. In the Version panel, select any two versions that you want to compare.

2. Click the Compare button at the bottom of the panel.

3. In the History Version Contrast dialog box that appears, view the differences between the two versions.

Comparison content:

• Wizard mode API: Displays differences in request parameters and response parameters, including changes to attributes such as parameter name, type, and whether a parameter is required.

• Script mode API: Displays text differences in SQL scripts, with added, deleted, and modified lines highlighted.

Version comparison is especially useful in team collaboration scenarios, helping reviewers quickly understand the content of each change.

Version rollback

When a new version is abnormal or does not meet expectations, you can roll back the API to a previous stable version.

Procedure:

1. In the Version panel, find the target historical version.

2. Click the Roll Back button in the Actions column of that version.

3. In the Confirm Rollback dialog box that appears, click Confirm.

Version management strategy

Good version management practices can significantly reduce the risk of production incidents.

• Change records: Each time you submit, clearly describe the changes and reasons in the submission notes so that team members can understand the context through version comparison.

• Gray release verification: For major changes, we recommend that you fully verify in the test environment before publishing to the production environment.

• Quick rollback: When an issue is detected online, use version rollback to restore the service first, then investigate the root cause. Rollback is faster than modifying and republishing, minimizing business impact.

• Regular cleanup: For APIs that have not been used for a long time, unpublish and clean them up promptly to reduce management complexity and potential security risks.

Collaboration workflow for testing and publishing

In team collaboration scenarios, the following workflow is recommended:

1. Developers create and configure the API on the Service Development page.

2. Developers test the API in the development environment to verify functionality.

3. Developers submit the API to generate a new version and initiate a publishing request.

4. Approvers review the publishing request in the approval center and can use the version comparison feature to view the changes.

5. After approval, developers execute the final publish operation.

6. Operators perform online testing and monitoring of the published API on the Service Management page.

7. If issues are found, quickly restore the API through version rollback, or unpublish it for repair.

This workflow helps teams achieve efficient full-lifecycle API management while ensuring publishing quality.

Limitations of response examples

The API editing page supports setting a normal response example to display the expected response data structure in the API documentation. Note the following:

• No automatic synchronization: Test results from the API testing page are not automatically updated as the normal response example. You need to manually edit or paste the response example on the API editing page.

• Size limit: The normal response example has a maximum character count limit. If the example data is too large (for example, containing hundreds of records), saving may fail. Keep only 2 to 3 typical records as the example.

• Takes effect after publishing: After modifying the normal response example, you must resubmit and publish the API for the changes to take effect in the API Gateway documentation.

Handling data source table structure changes

When the table structure of the data source associated with an API changes (such as adding columns, deleting columns, or modifying column types), published APIs do not automatically detect these changes. If not addressed, the following issues may occur:

Procedure:

1. Go to the API editing page and modify the API configuration based on the table structure changes.

   1. Wizard mode: Reselect the table, and the system automatically refreshes the column list.

   2. Script mode: Manually modify the column names or table name in the SQL statement.

2. After saving the configuration, retest to verify the changes.

3. Submit and republish the API.