Dataphin:Create an API based on a model

Step 1: Select a method to create an API

1. In the top menu bar of the Dataphin home page, choose Service > API Development.

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

3. In the New API dialog box, select Model API.

Step 2: Configure the parameters for the model API

1. On the New API page, configure the parameters.

   Parameter		Description
   Basic Information	API Name	Enter a name for the API. The naming conventions are as follows: The name can contain only Chinese characters, letters, digits, and underscores (_). The name must be 4 to 42 characters in length. The name must start with a letter. The name must be globally unique.
   	Model	Enter a name for the model. The name cannot exceed 256 characters.
   	Protocol Type	Select the protocol for the API. You can select OpenAI Compatible or DashScope. The API path is determined by the protocol type. For more information, see Chat and Image Generation.
   	Request Method	The default value is GET. This parameter cannot be changed. GET: Requests a specific resource from the server.
   	API Group	Select an API group that is configured in the current project. To create one, see Create a service group.
   	Description	Enter a brief description of the API. The description can be up to 128 characters in length.
   	Protocol	The protocol for the data generation API. You can select HTTP or HTTPS. HTTP: Hypertext Transfer Protocol (HTTP) is the most widely used network protocol. HTTPS: If the gateway is an Alibaba Cloud API Gateway instance (dedicated or shared), you can select HTTPS. Make sure that the SSL Certificate for the independent domain is valid to ensure successful API calls. To configure an SSL certificate, choose Platform Management Network Configuration and go to the Network Configuration page.
   	Invocation Mode	Used for communication between the client and the server to retrieve or process data. You can select synchronous or asynchronous invocation. The default is synchronous invocation. Synchronous Call: After the client sends a request, it must wait for the server to return a result before it can send other requests. For complex search statements, the response time is long and server connections are occupied during the wait. This increases the server load. This mode is suitable for scenarios that require high real-time performance and short processing times. Asynchronous Invocation: After the client sends a request, it does not need to wait for the server response and can continue to send other requests. The server notifies the client after processing is complete. When you retrieve data in batches, this mode can reduce the duplication rate of database query results and use DataService Studio APIs for data retrieval. This mode is suitable for scenarios with long processing times and low real-time requirements, such as batch processing.
   	Execution Timeout	This parameter is available when the invocation mode is asynchronous. It is used to monitor the SQL execution duration. The default value is 60 seconds. You can set it to an integer from 1 to 7,200 (2 hours).
   	Timeout	The maximum duration for an API call. If the invocation mode is synchronous, the default value is 30 seconds. You can set it to an integer from 3 to 60. If the invocation mode is asynchronous, the default value is 600 seconds. You can set it to an integer from 3 to 7,200 (2 hours). If an API call exceeds the configured timeout period, an error is reported to help you promptly detect and handle exceptions. For more information about viewing exceptions, see View and manage Service Monitoring APIs.
   	Version Number	Enter the version number for the API. Each configuration has a version number for comparison with the previous version. The version number can be up to 64 characters in length and must be unique for the API.
   	Return Type	The default value is JSON.
   Backend Service Configuration	Mode	You can select Basic or Dev_Prod mode. In Basic mode, the production database is read during development, submission, and publishing. In Dev-Prod mode, the developer database is read during development and submission, and the production database is read after publishing.
   	Request Method	The request method used to forward calls to the backend service. Only POST is supported. POST: If you select POST, you can select BODY for the request parameters.
   	API Data Source	Select the data source for the API. To create a data source, see Create an API data source.
   	Service Timeout	This setting specifies the timeout period for monitoring calls that are forwarded to backend services. If a call to a backend service exceeds the configured Service Timeout period, the API call reports a timeout error, which lets you promptly detect and handle exceptions in API calls. For more information about how to view exceptions, see and View and Manage Service Monitoring APIs.
   	Service Path	The service path is determined by the protocol type and model type. If the protocol type is OpenAI compatible, the supported model types are Chat and Custom. If the protocol type is DashScope, the supported model types are Chat, Image Generation, and Custom. When you select a model type, the system displays the corresponding service path. For example, if the URL of the API data source is http://dashscope.aliyuncs.com:*****/api/example and the Service Path is /compatible-mode/v1/chat/completions, the full URL of the backend service is http://dashscope.aliyuncs.com:*****/api/example/compatible-mode/v1/chat/completions. If you select a custom service path, the path must start with a forward slash (/) and cannot exceed 128 characters.
   Request Parameters	Parameter Name	The public parameter that users use directly when they access the API. The name can be up to 128 characters in length.
   	Parameter Location	You can select Headers, Parameters, or Body. Headers: The parameter is added to the header during request parameter parsing. Parameters: The parameter is appended to the data source URL during request parameter parsing. Body: If there are multiple parameters, they are encapsulated into a body during request parameter parsing.
   	Parameter Type	If Parameter Location is set to Body, you can set this parameter to Array(int), Array(string), or Object. If Parameter Location is set to another value, the supported parameter types include DOUBLE, FLOAT, STRING, DATE(yyyy-MM-dd HH:mm:ss), BOOLEAN, INT, LONG, SHORT, and BIGDECIMAL. Select the parameter type that corresponds to the bound field.
   	Default Value	If no value is passed during the backend service call, the default value is used. You can enter up to 1,000 characters. If the parameter type is STRING, there is no character limit.
   	Example	Enter an example value for the request parameter to help developers understand it. You can enter up to 1,000 characters.
   	Description	Enter a brief description of the request parameter. You can enter up to 1,000 characters.
   	Required	If this parameter is required and no value is passed during the API call, the call fails.
   Test		You can run a test to check whether the response from the large model meets your expectations. After you configure the request parameters, click the Test button. In the Send Test Request dialog box, enter trial values for the request parameters and click the Start Test button. The system encapsulates the request parameters, sends the request body to the large model, and returns the response.
   Response Parameters	Parameter Name	The public parameter name that is returned to the user by the API. The name can be up to 128 characters in length.
   	Parameter Type	The supported response parameter types include DOUBLE, FLOAT, STRING, DATE(yyyy-MM-dd HH:mm:ss), BOOLEAN, INT, LONG, SHORT, BIGDECIMAL, Array(int), and Array(string). Select the parameter type that corresponds to the bound field.
   	Example	Enter an example value for the response parameter to help developers understand it. You can enter up to 1,000 characters.
   	Description	Enter a brief description of the response parameter. You can enter up to 1,000 characters.
   	Response Parameter Value Path	Only the JSON format is supported. If the returned data is nested in multiple layers, you must configure the corresponding response parameter path. You can click View Configuration Instructions to configure the value path of the response parameter based on the example, or enter a keyword to search for a matching path.

2. Click Submit to create the API.

What to do next

• After you generate an API, you must test and publish it to the DataService Studio marketplace so that it can be called by applications. For more information, see Test and Publish an API.

• To delete the API, manage its versions, or transfer ownership, see View and manage APIs.