Create an API (service unit) using the codeless UI

Prerequisites

To generate an API based on a service unit, you need to create a service unit first. For more information, see Create a service unit.

Limits

• When using API paged queries, you need to set field sorting to ensure stable order of returned results, avoiding duplicate or missing results in paged queries. Only when using API paged queries, paging parameters (PageStart and PageSize) information is displayed on the API debugging or testing page.

• When calling an API, you can use PageStart and PageSize to set paging regardless of whether paged queries are enabled.

Permission description

Project administrators and developers of the service can generate APIs.

Data sources that support pagination and sorting

Y indicates support. N indicates no support.

Required sorting: If the data source type requires mandatory sorting, you need to configure parameters in the API or set the OrderByList parameter when calling to specify sorting for paged queries.

Notes

The request parameters and response parameters of an API must be obtained from the same service unit (single physical table service unit or multiple physical table service unit). Otherwise, the API cannot be called properly.

Step 1: Select a method to generate an API

1. In the top navigation bar of the Dataphin homepage, choose Service > API Development.

2. In the upper-left corner, select a project. In the navigation pane on the left, click API Service. On the API page, click +Create API.

3. In the Create API dialog box, select Service Unit API-Wizard Mode.

Step 2: Configure API parameters

1. On the Create API page, configure the basic information and parameters of the API.

   Basic API information configuration

   Parameter	Description
   API Name	Enter a name for the API. The name must meet the following requirements: It can contain only Chinese characters, letters, digits, or underscores (_). It must be 4 to 100 characters in length. It must start with a letter. It must be globally unique.
   Request Method	API request methods include GET and LIST: GET: Requests the server to obtain a specific resource. LIST: Requests the server to obtain a portion of resources.
   Data Update Frequency	Defines the update frequency of the data returned by the API, allowing callers to understand the timeliness of the data. Supported update frequencies include Daily, Hourly, Every Minute, and Custom. If you select Custom, you can enter up to 128 characters.
   API Group	Select the group to which the API belongs. To create a group, see Create a service group.
   Result Pagination	When the request method is List, you can set result pagination. After enabling, you must specify sorting fields to ensure stable query results, avoiding duplicate or missing results in paged queries. After disabling, the API debugging or testing page does not display paging parameters (PageStart and PageSize). You can uncheck Hide Parameters to display paging parameters.
   Description	Enter a brief description of the API. The description cannot exceed 128 characters.
   Protocol	The interface protocol for the data generation API. HTTP and HTTPS are supported. HTTP: Hypertext Transfer Protocol. It is the most widely used network protocol. HTTPS: If the gateway is configured as an Alibaba Cloud API Gateway (dedicated or shared instance), you can select the HTTPS protocol. Ensure that the SSL Certificate for the independent domain is valid to prevent call failures. To configure an SSL certificate, choose Platform Management Network Configuration and go to the Network Configuration page.
   Timeout	The maximum duration to monitor an API call. The default value is 3 seconds. You can set this parameter to an integer from 3 to 60. If an API call exceeds the specified Timeout, an error is reported. This helps you promptly find and handle API call exceptions. For more information about how to view exceptions, see Manage Service Monitoring APIs.
   Cache Settings	Supports Enable or Disable. If enabled, you need to configure Cache Timeout. The default is 300 seconds, and you can set a positive integer between 60 and 1,000,000 seconds (approximately 277.78 hours).
   Version Number	Enter the version number of the API. Each configuration has its own version number for comparison with previous versions. The version number must be unique for this API. The naming requirements are as follows: It cannot exceed 64 characters. It can contain uppercase and lowercase letters, digits, underscores (_), periods (.), and hyphens (-).
   Return Type	Default is JSON.
   Return SQL	Controls whether the API response includes the SQL statement that is executed. Select Yes (Enable): The API response returns the physical SQL statement that the database executes. Select No (Disable): The API response displays the original SQL script.

   API request parameters and response parameters configuration

   When configuring API Request Parameters and Response Parameters, you need to first determine the source of the input and output parameters (Service Unit), then add the input and output parameters to the Request Parameters and Response Parameters areas respectively, and finally configure the basic information of the Request Parameters and Response Parameters.

   1. In the Parameter Checking area, select Mode and Service Unit. The page will display all fields in the selected service unit below.

      Parameter	Description
      Mode	Supports two modes: Basic or Dev_Prod. In Basic mode, development, submission, and online publishing all read from the production library. In Dev-Prod mode, development and submission read from the development library, while online publishing reads from the production library.
      Service unit fields	Supports copying all table fields or individual fields. Abnormal fields are marked with an alert icon. You need to check whether the service unit to which the field belongs has been published to the production environment or whether the service unit exists.
      Actions	Data Preview: Click to open the Data Preview panel. The system returns the first 100 records of the current service unit by default. You can choose to return 10, 50, 100, 500, or 1000 records. View Row-Level Permissions: This operation is available when row-level permissions are enabled for the referenced service unit. Click to open the View Row-Level Permissions panel, which displays row-level permission information for the selected service unit, including permission name, description, control field, associated table, and associated field. When the mode is Basic, it displays the service unit row-level permissions associated with the production environment. When the mode is Dev-Prod, it displays the service unit row-level permissions associated with both development and production environments.

   2. Select one or more fields from the list on the left side of the dual list box, click the icon to add the selected API fields to the Request Parameters column on the right, and then configure the basic information of the request parameters.

      

      Parameter	Description
      Parameter Name	The publicly exposed parameter that users directly use when accessing the API. The name must meet the following requirements: It can contain letters, digits, or underscores (_). It must start with a letter. It must be 1 to 64 characters in length.
      Associated Column	The invisible parameter that is actually accessed when the API is called.
      Parameter Type	Parameter types include DOUBLE, FLOAT, STRING, DATE(yyyy-MM-dd HH:mm:ss), BOOLEAN, INT, LONG, SHORT, BYTE, BIGDECIMAL, and BINARY. The service unit field type should be consistent with the request parameter field type. You can select the corresponding field type.
      Operator	The processing method for request parameters when calling the API. For currently supported operators and their meanings, see Operators supported for API development.
      Example	Enter an example of the request parameter value to help developers understand it. For example, if the parameter name is ID, the parameter type is Int, and the operator is =, you can set the example to 5. Enter up to 1000 characters.
      Description	Enter a brief description of the request parameter. The maximum length is 1000 characters.
      Required	Specifies whether the request parameter is required when calling the API. Select No: The SQL statement for calling the API can be executed without this parameter. Select Yes: The SQL statement for calling the API cannot be executed without this parameter. For example, if the request parameter is id, the request parameter is required, and the response parameter is name, executing the following statements will have different results: select name from tableA,where id=5;: Returns the name field and corresponding data. select name from tableA;: The SQL statement execution fails.

   3. Select one or more fields from the list on the left side of the dual list box, click the icon to add the selected API fields to the Response Parameters column on the right, and then configure the basic information of the response parameters.

      

      Parameter	Description
      Parameter Name	The publicly exposed parameter, which is the final parameter name displayed to users when the API returns results. The name must meet the following requirements: It can contain letters, digits, or underscores (_). It must start with a letter. It must be 1 to 64 characters in length.
      Associated Column	The invisible parameter that is actually accessed when the API is called.
      Parameter Type	The data format when calling the API. Parameter types include DOUBLE, FLOAT, STRING, DATE(yyyy-MM-dd HH:mm:ss), BOOLEAN, INT, LONG, SHORT, BYTE, BIGDECIMAL, and BINARY. The service unit field type should be consistent with the response parameter field type. You can select the corresponding field type.
      Example	Enter an example of the response parameter value to help developers understand it. Enter up to 1000 characters.
      Description	Enter a brief description of the response parameter. Enter up to 1000 characters.

   4. Select one or more fields from the list on the left side of the dual list box, click the icon to add the selected API fields to the Sort Settings column on the right, adding the fields that need to be sorted to the sort settings area.

      Sort fields are optional. If paged queries are enabled, you must specify sort fields to ensure stable query results, avoiding duplicate or missing results in paged queries. If sorting parameters are specified in the request, the sorting specified in the parameters takes precedence.

      

      Parameter	Description
      Sort Field	The fields in the service unit to use for sorting.
      Sort Order	Ascending or descending.
      Actions	Drag the icon next to a field name to change its sort priority. You can also click the icons in the Actions column to move a field up or down. The icons from left to right are Move Up, Move Down, and Delete. Note The sort priority decreases from top to bottom. If the API request uses the GET method, the service returns the first result after sorting.

2. Click Submit to verify that the fields referenced by the API exist in their respective service units. After verification passes, the API generation is complete.