Create, publish, and call an API (cloud-native API Gateway)

1. Create a gateway instance

A gateway instance is the engine that processes API requests.

1. Log on to the Cloud-native API Gateway console. In the left-side navigation pane, click Instance.

2. Select a region from the top navigation bar.

   Important

   The region must be the same as the region of your DataWorks workspace.

3. On the Instance page, click Create Instance.

4. On the purchase page, configure the following parameters:

   • Commodity Type: Pay-as-you-go and Subscription are supported. For testing purposes, you can select pay-as-you-go.

   • Gateway Name: Enter a custom name that is easy to identify, such as dataservice-prod.

   • Gateway Specification: Select single-node for testing or multi-node for production SLA compliance.

   • Network Access Type: Select Public or Public + Private to enable Internet access. Using public access incurs traffic fees.

   • VPC: Select a VPC.

     Important

     We strongly recommend using the same VPC as the serverless resource group in the prerequisites. If the VPCs differ, you must manually create a backend service later.

   • Zone Selection: You can select Auto Assign or manually assign instances across different zones and vSwitches.

   • Resource Group: Select a resource group based on your resource management policy.

5. Click Buy Now and complete the payment. The instance creation takes about 1 to 5 minutes. When the instance status changes to Running, the instance is created.

Create a gateway instance.

2. Add a domain name

A domain name serves as the public access entry point for the API.

1. In the left-side navigation pane of the Cloud-native API Gateway console, click Domain Name. Make sure the region at the top matches the gateway instance.

2. Click Add Domain Name and configure the following information:

   • Domain Name: Enter your own domain name, such as api.example.com. Independent domain names used in China regions must complete ICP filing.

   • Protocol: Select HTTPS for secure data transmission. You must also select an existing SSL certificate.

   • Other Settings: Enable Force HTTPS and Enable HTTP/2, and select a TLS Version based on your security requirements.

Add a domain name.

3. Create a REST API

A REST API groups APIs under a shared Base Path. A DataWorks workflow binds to a REST API.

1. In the left-side navigation pane of the Cloud-native API Gateway console, click API. Make sure the region at the top is correct.

2. Click Create API. On the Create API page, select Create under the REST API card.

3. In the Create REST API panel, configure the following settings:

   • API Name: Name your API collection. The name must be globally unique within the current region, such as dataservice-user-api.

   • Base Path: The base path of the API, which is part of the URL. For example, set it to /v1. The final access path will be Protocol://DomainName/BasePath/APIPath.

   • Version Management: Enable as needed.

Create a REST API.

1. Create a workflow

A workflow organizes related APIs and associates them with a REST API in API Gateway.

1. Go to the DataWorks console. In the left-side navigation pane, go to Data Services > Service Development.

2. Click the create icon in the upper-left corner and select Create Workflow.

3. In the Create Workflow dialog, configure the following settings:

   • Workflow Name: Enter a custom name that is unique within the workspace, such as User Query Workflow. The name must be 4 to 50 characters in length.

   • Gateway Type: Select Cloud-native API Gateway.

   • REST API: From the drop-down list, select the REST API that you created in Step 1 (for example, dataservice-user-api). If it does not appear, click the Refresh button.

     Important

     After a workflow is associated with a REST API, the binding cannot be changed. Proceed with caution.

2. Generate an API in wizard mode

1. On the Service Development page, hover over the create icon in the upper-left corner and click Create API > Generate API.

2. In the Generate API dialog, select Wizard Mode and configure the basic API information:

   • Location: Select the Workflow created in the previous step (User Query Workflow).

   • API Name: Enter a name for the specific API, such as Query User by User ID.

   • APIPath: The specific path of the API, such as /user/info. It is concatenated with the Base Path to form the complete URL path. The API Path must start with / and cannot exceed 200 characters in length.

   • Request Method: Select GET or POST. When GET is selected, request parameters can only be placed in the QUERY string.

   • Response Type: Select JSON.

3. Click Create to go to the graphical API editing page.

   Note

   To create an API in script mode, see Create an API in script mode.

3. Configure the API

On the API editing page, follow the Select Table > Select Parameters > Configure Parameters process to define API logic.

1. Select a table (data source and table)

   In the Select Table section on the left side of the page, configure the following settings:

   • Data Source Type: Select MaxCompute(ODPS).

   • Data Source Name: Select the data source that you configured in the prerequisites.

   • Data Table Name: Select the user_info table.

   • If you use a MaxCompute data source, you must configure Acceleration Method to improve performance.

2. Select parameters (request and response)

   After you select a table, the Select Parameters section below lists all columns of the table.

   • Configure request parameters: Select the user_id column and click Set as Req Param.

   • Configure response parameters: Select the user_id and user_name columns and click Set as Resp Param.

3. Configure request parameter details: On the Request Parameters tab on the right side of the page, set the Sample Value for the user_id parameter (for example, 10001). This helps with subsequent testing.

   Best practice: Set indexed columns as request parameters to optimize query performance.

4. Configure service resource group and environment

   In the Service Resource Group section on the right side of the page, configure the following settings:

   • Resource Group Type: You must select Exclusive Resource Group for Data Service and select a resource group that is associated with the current workspace from the drop-down list.

   • Environment Configuration:

     • Timeout: The maximum time that Cloud-native API Gateway waits for a response from DataWorks, such as 3 seconds.

     • Maximum Number of Data Records for a Single Request: The maximum number of records returned by a single API call, such as 2000.

5. Configure security authentication

   Configure security authentication on the right side of the page. After enabling consumer authentication, select one of the following authentication types.

   Note

   DataWorks automatically creates a consumer with the same name as the workspace in Cloud-native API Gateway. You do not need to manually create one.

   Authentication method	Description	Applicable scenario
   API Key	The client adds credentials to requests in a specified format, and the gateway verifies their validity and permissions. Suitable for non-sensitive operations. Less secure than JWT and HMAC — protect credentials carefully.	Suitable for lightweight and quick integration scenarios with moderate security requirements.
   JWT	JSON Web Token (JWT) uses HMAC, RSA, or ECDSA signatures to securely transmit verifiable claims between client and server. Enables identity verification and access control at the gateway.	Suitable for distributed systems and single sign-on (SSO) scenarios.
   HMAC	The client signs request content with a signing key and sends the signature with the request for server verification.	Suitable for scenarios with high requirements on data integrity and tamper prevention.

6. Save the API: After you complete all configurations, click the Save icon in the top toolbar.

1. Test the API

An API must pass testing before it can be submitted.

1. On the API editing page, click the Test APIs button in the toolbar.

2. In the Test APIs dialog, enter an existing sample value for the user_id request parameter (for example, 10001), and then click Start Test.

3. View the Response Details on the right side to verify whether the data meets expectations. Response Duration can be used to evaluate performance.

4. If the test fails, check the data source, table, parameters, or resource group configurations based on the error message.

2. Submit the API

After a successful test, submit the API to generate a deployable version.

1. On the API editing page, click the Submission button in the toolbar.

2. After the submission succeeds, the system automatically generates an API version. You can view it on the Version Management tab on the right side.

3. If an approval process is configured for your workspace, the API version status will be To Be Requested. You need to click Request to Publish to initiate a request. After the approver approves the request, the status changes to Can Be Published.

   If no approval process is configured, the version status is usually Can Be Published directly.

3. Deploy the API to Cloud-native API Gateway

Deploy the API to the production environment.

1. On the Version tab on the right side of the API editing page, find the version with the Can Be Published status and click Publish in the Actions column.

2. In the Publish API to Cloud-native API Gateway dialog, configure the following three required settings:

   • Domain Name: Select the domain name that you added in Step 1.

     Important

     All APIs under the same REST API share the same domain name. Changing the domain name during deployment will affect the domain name used to call all APIs under the same REST API.

   • Gateway Instance: Select the gateway instance that you created in Step 1.

   • Backend Service:

     • If the VPC of the gateway instance is the same as the VPC of the DataWorks resource group, select Default.

     • If the VPCs are different, you must select a backend service created in Cloud-native API Gateway.

       Create a backend service

       Perform this step only if the VPC selected when creating the gateway instance in Step 1 is different from the VPC of the serverless resource group. If the VPCs are the same, skip this section.

       A backend service bridges connectivity between two different VPCs for Data Service requests.

       1. In the Instance list in the Cloud-native API Gateway console, click the ID of the target instance.

       2. In the left-side navigation pane of the instance details page, click Service.

       3. Click Create Service. If prompted, first create a source on the Source tab.

       4. When creating a service, configure the service name and associate it with the source that you created.

       Create a backend service.

Deploy an API to multiple gateway instances

In the Version panel, click Publish for the version with the Can Be Published status. In the Publish API to Cloud-native API Gateway dialog, select a different Gateway Instance to deploy the API to the corresponding gateway instance. You can repeat this operation to deploy the same API to different gateway instances.

Multi-version display in service management

After an API is deployed to multiple gateway instances, the display on the Service Management page changes as follows.