A registered API lets you register existing services to the service platform for unified management. This topic describes how to create an API by registration.
Step 1: Select the method to create an API
On the Dataphin homepage, choose Service > API Development.
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 + Create API button.
In the Create API dialog box, select Registered API.
Step 2: Configure the parameters for the registered API
Configure the parameters on the Create API page.
Parameter
Description
API basic information
API Name
The naming convention for API names is as follows:
Can only contain Chinese characters, letters, numbers, or underscores (_).
Must be 4 to 100 characters long.
The name must start with a letter.
The name must be globally unique.
Operation Type
API request methods include GET and LIST:
GET: Requests the server to retrieve a specific resource.
LIST: Requests the server to retrieve 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 an API group configured in the current project. To create a new group, see Create a service group.
Description
Enter a brief description of the API. Limited to 128 characters.
Protocol
The protocol for the data generation API. HTTP and HTTPS are supported.
HTTP: The 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. To prevent call failures, make sure that the SSL Certificate for the independent domain is valid. To configure the SSL Certificate, go to the Network Configuration page from Platform Management.
Timeout
The maximum duration for an API call. The default value is 3 seconds. You can set this to any 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 View and manage service monitoring APIs.
Version Number
The version number of the API. Each configuration has a version number, which you can use to compare it with previous versions. The version number can be up to 64 characters in length and must be unique within the API.
Return Type
Default is JSON.
Backend service configuration
Mode
Supports two modes: Basic or Dev_Prod.
In Basic mode, development, submission, and online publishing all read from the production database.
In Dev-Prod mode, development and submission read from the development database, while online publishing reads from the production database.
Request Method
The request method used to forward calls to the backend service. POST and GET are supported.
POST: If the request method is POST, request parameters can be placed in the BODY.
GET: If the request method is GET, request parameters cannot be placed in the BODY.
API Data Source
Select the data source for the registered API. To create a data source, see Create an API data source.
Service Timeout
Used to monitor the duration of forwarding calls to the backend service. If the call to the backend service exceeds the specified Service Timeout, an error will occur during the API call due to backend service call timeout, allowing you to promptly identify and handle abnormal API call situations. For details about viewing abnormal situations, see View and manage service monitoring APIs.
Service Path
The path for calling the backend service must start with a forward slash (/) and is limited to 128 characters.
For example, if the URL of the API data source is
http://88.100.19.58:*****/api/exampleand the service path is/abc/djd, the complete URL of the backend service ishttp://88.100.19.58:*****/api/example/abc/djd.Request parameters
Parameter Name
The publicly exposed parameters that users directly use when accessing the API. Limited to 128 characters.
Parameter Location
Supports Headers, Parameters, and Body.
Headers: When parsing request parameters, they will be added to the header position of the parameters.
Parameters: When parsing request parameters, they will be concatenated with the URL of the data source.
Body: When parsing request parameters, if there are multiple parameters, they will be encapsulated into a single Body.
Parameter Type
If the parameter location is Headers or Parameters, the supported parameter types are 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.
If the parameter location is Body, the following types are also supported in addition to the preceding types: Array(int), Array(string), Object, Array(double), Array(float), Array(Date(yyyy-MM-dd HH:mm:ss)), Array(boolean), Array(long), Array(short), Array(BigDecimal), and Array(Object).
Default Value
The default value used in the backend service call if no value is passed. You can enter up to 1,000 characters. If the parameter type is STRING, there is no character limit.
Example
An example value for the request parameter to help developers. The example can be up to 1,000 characters in length.
Description
A brief description of the request parameter. The description can be up to 1,000 characters in length.
Required
For required parameters, if no parameter value is provided when calling the API, the API call will fail.
Test
You can test the API to check whether the response is as expected.
After you configure the request parameters, click the Test button. In the Test Request dialog box, enter test values for the parameters and click the Start Test button. The system then encapsulates the parameters, sends the request body, and returns the response.
Smart Add
This feature is available if the operation type is GET and you have tested the request parameters. Click the Smart Add button. The system automatically extracts the first-layer parameters from the response and adds them to the return parameter list. The extracted information includes the parameter name, return parameter path, and parameter type.
Return parameters
Parameter Name
Required. The publicly exposed parameter name that is displayed to users when the API returns a response. The name can be up to 128 characters long.
Return Parameter Path
Only the JSON format is supported. If the returned data has multiple nested layers, you must configure the corresponding path to retrieve the parameter value. Click View Configuration Instructions to see an example of how to configure the path, or enter a keyword to search for a matching path.
Parameter Type
If you have tested the return parameter path, the system automatically detects the data type based on the test result. You can select the parameter type that corresponds to the bound field. Supported types include DOUBLE, FLOAT, STRING, DATE(yyyy-MM-dd HH:mm:ss), BOOLEAN, INT, LONG, SHORT, BIGDECIMAL, Array(int), Array(string), Object, Array(double), Array(float), Array(Date(yyyy-MM-dd HH:mm:ss)), Array(boolean), Array(long), Array(short), Array(BigDecimal), and Array(Object).
Example
An example value for the return parameter to help developers. The example can be up to 1,000 characters in length.
Description
A brief description of the return parameter. The description can be up to 1,000 characters in length.
Click Submit to complete the API creation.
What to do next
After creating the API, you need to test it and publish it to the DataService Studio marketplace for subsequent applications to call the API. For more information, see Test and publish APIs.
To delete an API, manage versions, transfer ownership, or perform other operations, see View and manage APIs.