API testing, publishing, and version management

Test an API in development

You can test an API in development on the Service Development page, which is 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: Displays the complete request information for the API call, including the request path, headers, and body. This helps you verify that the request is structured correctly.

• Response Details: Displays the response data from the API, which is the actual query result. You can compare the response content with the expected result to confirm that the API logic is correct.

• Response Duration: Displays the end-to-end response time for the API request. You can use this information to evaluate the API's performance. If the latency is high, consider optimizing the query logic or data source configuration.

If a test fails, review the returned error message, make the necessary changes, and test the API again.

Test a published API

You can test a published API on the Service Management page, which serves as the production environment. This allows you to verify the API's behavior in the production environment. Before you perform this test, you must 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 that values are configured for all request parameters.

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

Notes:

• The Test APIs page provides only online testing functionality. You cannot use this page to update the normal response example for the API.

• If an API is configured with Pagination for Return Results, whether the returned data is ordered depends on the underlying data source. To ensure 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.

Interpret and optimize test results

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

Once the test results meet your expectations, you can publish the API to API Gateway.

Prerequisites

Before you publish an API, make sure that the following requirements are met:

• API Gateway activated: Go to the API Gateway console to activate the service.

  Important

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

• API group created: When an API is published, it is deployed to the API Gateway group associated with its Business Process. Make sure that the Business Process is correctly associated with an API Gateway group. You can verify the group name by right-clicking the Workflow and selecting Change.

Publishing process

The API publishing process follows three steps: Submit → Approve → Publish.

Step 1: Submit the API

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

2. In the upper-right corner, click Submission.

3. A successful submission automatically generates an API version, such as V1 or V2. You can view the status of this version in the Version panel that appears on the right.

Step 2: Request to publish and wait for approval

1. In the Version panel on the right, find the API version that you want to publish and click Publish.

2. Follow the on-screen prompts to enter a reason for the request, and click Requested Permissions to submit the publish request.

3. If an approval process is configured for the workspace, the publish request must be reviewed in the DataWorks Approval Center. Approvers can view the request details and process the request on the Approval Center > To Be Processed page.

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

Step 3: Publish the API

1. After the request is approved, on the API editing page, click Version in the right-side navigation pane. Find the API version with the Can Be Published status.

2. Click the Publish button and wait for the system to indicate that the publishing is successful.

3. After the API is published, DataWorks deploys it to the API Gateway group associated with the API's Business Process.

Verify publication

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

• View in API Gateway: Log on to the API Gateway console. In the left-side navigation pane, choose Manage APIs > Service List to view the published API information. You can also configure policies such as throttling and access control.

• Calling from applications: If the API is intended for your own applications, you need to create an application in API Gateway, authorize the application to access the API, and then call it using an encrypted signature with an AppKey and AppSecret. API Gateway also provides SDKs for mainstream programming languages to help you quickly integrate the API into your applications. For more information, see Examples of calling an API. For SDK integration, see Download and use an SDK.

• Protocol change: For a published API, go to the Service Management > Published APIs tab. In the Actions column for the API, choose More > Change Protocol to modify its access protocol, for example, from HTTP to HTTPS. The protocol change takes effect immediately. However, if you delete the original protocol, calls to the API using that protocol will fail. Proceed with caution.

List on Alibaba Cloud Marketplace (optional)

Alibaba Cloud Marketplace covers categories such as finance, AI, e-commerce, transportation and geography, living services, corporate management, and public affairs. Thousands of API products are available for sale, providing a platform to help you quickly achieve data monetization. Alibaba Cloud Marketplace

After an API created or registered in DataService Studio is published to API Gateway, you can list it on Alibaba Cloud Marketplace for sale. This helps enterprises achieve data monetization and complete their commercialization process.

Requirements:

• Only enterprise accounts can join Alibaba Cloud Marketplace.

• Before listing an API, you must join Alibaba Cloud Marketplace as an ISV. For more information about the process, see Alibaba Cloud Marketplace onboarding process.

Procedure:

1. Go to the Alibaba Cloud ISV portal.

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

3. Click Create Product.

4. On the Access Information page, configure the parameters as guided, such as product name, pricing strategy, and API binding, to complete the listing process. For more information, see Instructions for integrating 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. In the API list on the Service Development page, double-click the name of the API you want to view 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 panel displays all historical version information for the current API, including:

   Note

   The Actions column for each version provides an API Details link. You can click it to view the complete configuration information for that version, including request parameters, response parameters, and data source configurations.

   Field	Description
   API ID	The unique identifier of the current API.
   Version	The version number, which increments with each submission (V1, V2, V3...).
   Submitted By	The user who submitted this version.
   Submitted At	The time this version was submitted, accurate to the second.
   Status	Publish (The current live version) Can Be Published (A version that has been tested and submitted) Batch Synchronization (A historical version)

Compare versions

When an API has undergone multiple iterations, you may need to compare different versions to understand the specific changes.

Procedure:

1. In the Version panel, select the 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 details:

• Wizard mode APIs: The comparison shows differences in request parameters and response parameters, including changes to parameter names, types, and whether they are required.

• Script mode APIs: The comparison shows text differences in the SQL script, highlighting added, deleted, and modified lines of code.

The version comparison feature is particularly useful in collaborative scenarios, helping reviewers quickly understand the specifics of each change.

Version rollback

If a new version causes issues or does not meet expectations, you can quickly roll back the API to a previous stable version.

Procedure:

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

2. In the Actions column for that version, click Roll Back.

3. In the Confirm that you want to roll back the current version dialog box, click Confirm.

Version management strategy

Good version management habits can significantly reduce the risk of online incidents:

• Track changes: When submitting a change, clearly describe the modification and the reason for it in the submission notes. This helps team members understand the context behind the changes by using version comparison.

• Canary validation: For major changes, we recommend that you perform thorough validation in a test environment before publishing to the production environment.

• Quick rollback: If an issue is discovered online, prioritize using the version rollback feature to restore the service before investigating the root cause. Rolling back a version is faster than modifying and republishing, which minimizes business impact.

• Regular cleanup: We recommend that you promptly unpublish and delete APIs that are no longer in use to reduce management complexity and potential security risks.

Collaborative workflow

In a team collaboration scenario, we recommend the following workflow:

1. A developer creates and configures the API on the Service Development page.

2. The developer performs tests in the development environment to confirm that the functionality is correct.

3. The developer submits the API, generating a new version and initiating a publish request.

4. An approver reviews the publish request in the DataWorks Approval Center and can use the version comparison feature to view the changes.

5. After approval, the developer performs the final publishing operation.

6. An operations engineer conducts online testing and monitoring of the published API on the Service Management page.

7. If a problem is found, the service is quickly restored by rolling back the version, or the API is unpublished to be fixed.

By following this process, teams can manage the entire API lifecycle efficiently while ensuring release quality.

Limitations of response examples

The API editing page allows you to set a Normal Response Example, which is used to display the expected response data structure in the API documentation. Note the following limitations:

• No automatic sync: The response from an API test does not automatically update the API's normal response example. You must manually edit or paste the response example on the API editing page.

• Size limit: The normal response example has a character limit. If the example data is too large, for example, containing hundreds of records, it may fail to save. We recommend that you keep only 2 to 3 typical records as an example.

• Changes take 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 schema changes

When the schema of a data source table associated with an API changes, such as when a field is added, deleted, or its type is modified, the published API does not automatically detect these changes. Failure to address these changes can lead to the following issues:

Procedure:

1. Go to the API editing page and modify the API configuration to reflect the schema change.

   1. Wizard mode: Reselect the table, and the system will automatically refresh the field list.

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

2. After saving the configuration, test the API again to verify the changes.

3. Submit and republish the API.