DataWorks: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 navigation pane on the left, click Instances.

2. In the top navigation bar, select a region.

   Important

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

3. On the Instances page, click Create Instance.

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

   • Product Type: You can select Pay-As-You-Go or Subscription. For testing purposes, you can use Pay-As-You-Go.

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

   • Gateway Specification: You can choose a single-node specification for testing. However, for production environments, use a multi-node gateway specification to ensure the SLA.

   • Network Type: Select Public Network or Public Network and Private Network to allow internet access. Public network traffic is billable.

   • VPC: Select a VPC.

     Important

     For simpler network connectivity, use the same VPC for both the gateway instance and the Serverless resource group you prepared earlier. If you use different VPCs, you must manually create a backend service later.

   • Zone Selection: You can select Auto-assign or manually assign instances to different availability zones and vSwitches.

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

5. Click Buy Now and complete the payment. Instance creation takes 1 to 5 minutes. The instance is ready when its status changes to Running.

For more information, see Create a gateway instance.

2. Add a domain name

A domain name is the public entry point for your API.

1. In the navigation pane on the left of the Cloud-native API Gateway console, choose Domains. Make sure the region selected at the top is the same as your gateway instance's region.

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

   • Domain Name: Enter your custom domain name, such as api.example.com. Custom domain names used in mainland China regions require ICP filing.

   • Protocol: Select HTTPS for secure data transmission. This requires an existing SSL certificate.

   • Other configurations: We recommend enabling Force HTTPS and Enable HTTP/2. Specify the TLS Version based on your security requirements.

For more information, see Create a domain name.

3. Create a REST API

A REST API is a logical container for managing a group of APIs that share the same Base Path. A business process in DataWorks is bound to a REST API.

1. In the navigation pane on the left of the Cloud-native API Gateway console, click APIs, and make sure the correct region is selected at the top.

2. Click Create API. On the Create API page, click Create on the REST API card.

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

   • API Name: Enter a globally unique name for your API collection in the current region, such as dataservice-user-api.

   • Base Path: The base path of the API, which is part of the URL. For example, /v1. The final request URL is protocol://domain/BasePath/APIPath.

   • Version Management: Enable this feature as needed.

For more information, see Create a REST API and add an interface.

1. Create a business process

A business process is used to organize a group of related APIs and bind them to a REST API in API Gateway.

1. Go to the DataWorks console. In the navigation pane on the left, choose Data Service > Service Development.

2. Click the new icon in the upper-left corner and select New Business Process.

3. In the New Business Process dialog box, configure the following settings:

   • Business Name: A custom name that is unique within the workspace, such as User Query Service. 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 the API does not appear, click Refresh.

     Important

     This binding cannot be changed, so choose carefully.

2. Generate an API in wizard mode

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

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

   • Target folder: Select the business process (User Query Service) that you created in the previous step.

   • API Name: The name of the API, such as Query User by User ID.

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

   • Request Method: Select GET or POST. With the GET method, request parameters must be in the query string.

   • Response Type: Select JSON.

3. Click Create to enter the API's visual editing page.

   Note

   To learn how to create an API in script mode, see Generate an API in script mode.

3. Configure the API

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

1. Select a table (data source and table)

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

   • Data Source Type: Select MaxCompute (ODPS).

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

   • Data Table Name: Select the user_info table.

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

2. Select parameters (request and response)

   After you select the table, the Select Parameters area below will list all fields of the table.

   • Configure request parameters: Select the user_id field, and then select Set as Request Parameter.

   • Configure return parameters: Select the user_id and user_name fields, and then select Set as Return Parameter.

3. Configure request parameter details. On the Request Parameters tab on the right side of the page, set a Sample Value for the user_id parameter, such as 10001. This is helpful for subsequent testing.

   Best practice: We recommend setting indexed fields as request parameters to optimize query performance.

4. Configure the service resource group and environment

   In the Service Resource Group area on the right, configure the following:

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

   • Environment Configuration:

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

     • Maximum number of records per request: Limits the maximum number of records returned in a single API call, for example, 2000.

5. Configure authentication

   Configure settings in the authentication area on the right. After you enable consumer authentication, you can choose one of the following three authentication types.

   Note

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

   Configuration method	Description	Use cases
   API Key	The client adds credentials to the request, which the gateway then validates. This method is best for non-sensitive operations and is less secure than JWT or AccessKey pair authentication. You must properly manage and protect the credentials.	Suitable for lightweight, quick integration and scenarios with general security requirements.
   JWT	JSON Web Token (JWT) is a standard for securely transmitting information between a client and a server. It uses HMAC, RSA, or ECDSA signatures to ensure the information is verifiable and trustworthy. JWT authentication can be used in the gateway to implement identity verification and access control.	Suitable for distributed systems and Single Sign-On (SSO) scenarios.
   HMAC	AccessKey pair signature authentication based on the HMAC algorithm requires the client to sign the request with a key. The server then verifies this signature.	Suitable for scenarios that require high data integrity and tamper resistance.

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

1. Test the API

You must test the API successfully before you can commit it.

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

2. In the API Test dialog box, enter an existing sample value (such as 10001) for the user_id request parameter, and click Start Test.

3. Check the Response on the right to confirm if the data is as expected. The Response Duration can be used to evaluate performance.

4. If the test fails, check your data source, table, parameter, or resource group configuration based on the error message.

2. Commit the API

After the test passes, commit the API to create a publishable version.

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

2. After a successful commit, the system automatically generates an API version. You can view it on the Version Management tab on the right.

3. If your workspace requires an approval process, the API status becomes Pending for Application. You must click Apply for Publishing to submit it for approval. Once approved, the status changes to Publishable.

   If no approval process is configured, the version status is usually set directly to Publishable.

3. Publish the API

This final step deploys the API to the production environment.

1. On the Versions tab of the API editing page, find the version with the status Publishable and click Publish in the Actions column.

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

   • Domains: Select the domain name you added in Step 1.

     Important

     All APIs under the same REST API share the same domain name. Any changes to the domain name during publishing will affect all APIs under the same REST API.

   • Gateway Instance: Select the gateway instance 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, you can select Default.

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

       Create a backend service

       Do this only if the VPC you selected for the gateway instance in Step 1 differs from the VPC of the Serverless resource group. If the VPCs are the same, skip this section.

       A backend service enables Data Service requests to cross VPC boundaries.

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

       2. On the instance details page, choose Services from the navigation pane on the left.

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

       4. When you Create Service, set a service name and associate it with the source you created.

       For more information, see Create a service.