Configuring an Entry API Operator

Updated on 2024-08-30 GMT+08:00

View PDF

An API workflow starts with the Entry API operator. After the API workflow is published, it can be invoked through the Entry API operator. In the Entry API operator, you need to define the API workflow name, URL, parameter protocol, request method, reviewer, security authentication, and request parameters.

**Table 1** Entry API operator parameters
Parameter	Descriptions
API	Entry API name, that is, API workflow name An API name consists of 3 to 64 characters and starts with a letter. Only letters, numbers, and underscores (_) are allowed.
Request Path	Entry API access path, that is, API workflow access path, for example, /getUserInfo It is the part between the domain name and query parameters in the URL of a request path, for example, /blogs/xxxx shown in the following figure. Figure 1 API access path in the URL Braces ({}) can be used to identify parameters in a request path as wildcard characters. For example, /blogs/{blog_id} indicates that any parameter can follow /blogs. /blogs/188138 and /blogs/0 can both match /blogs/{blog_id}, and are processed by this API. In addition, duplicate request paths are not allowed for the same domain name. When a path parameter is used as a wildcard, the name is not unique. For example, /blogs/{blog_id} and /blogs/{xxxx} are considered as the same path.
Protocol	Protocol used to transmit requests. The exclusive edition supports HTTPS. HTTPS is recommended. It is an HTTP-based protocol with SSL or TLS encryption verification. It can effectively verify identities and protect data integrity. To access HTTPS APIs, you need to configure related SSL certificates or skip SSL verification.
Request Method	HTTP request method, indicating the type of the requested operation, such as GET and POST. The method complies with the resultful style. GET requests the server to return specified resources. This method is recommended. POST requests the server to add resources or perform special operations. The POST request does not have a body. Instead, it involves transparent transmission.
Description	A brief description of the API to create.
Tags	API tag. The tag is used to mark the API attributes. After the API is created, you can quickly search for the API by tag. A maximum of 20 tags can be set for an API.
Reviewers	A reviewer who has permissions to review APIs. Click Add to enter the Review Center page and click Add on the Reviewers tab page to add a reviewer.
Security Authentication	When creating an API, you can select one of the following security authentication modes. The three modes differ in how the API is called. You are advised to select App authentication, which is more secure that the other two modes. App authentication: After the API is authorized to an application, the key pair (AppKey and AppSecret) of the application is used for security authentication. The API can be called using an SDK or API calling tool. This authentication mode is highly secure and recommended. IAM authentication: After the API is authorized to the current account or another account, the user token obtained from IAM is used for security authentication. The API can be called using an API invoking tool. The security level of this mode is medium. Non-authentication: This mode allows all users to access APIs, which may pose security risks. It is recommended only for testing APIs. In this mode, no authentication information is required. The security level is low. You can use an API invoking tool or browser to directly call the API.
Display Scope	After the API is published, all users in the selected scope can view the API in the service catalog. Current workspace APIs Current project APIs Current tenant's APIs
Access Log	If you select this option, the API query result will be recorded and retained for seven days. You can choose Operations Management > Access Logs and select the request date to view the logs.
Min. Retention Period	Minimum retention period of the API publishing status, in hours. Value 0 indicates that the retention period is not limited. You can suspend, unpublish, or cancel authorization for an API only after the minimum retention period ends. The system notifies the authorized users. If all authorized users have processed the notifications or unbound the API from their apps, the API will be suspended or unpublished, or the API authorization will be canceled. Otherwise, the system will forcibly suspend, unpublish, or cancel authorization for the API when the minimum retention periods ends. For example, if the minimum retention period is set to 24 hours, the API can be suspended 24 hours after it is published. If the authorized user handles the notifications in the review center or unbind the API from the app, the API will be directly suspended. Otherwise, the API will be forcibly suspended when the minimum retention period ends.
Input Parameters	Parameters required for invoking the API workflow. An input parameter consists of the parameter location, parameter type, whether the parameter is mandatory, whether a null value is allowed, and the default value. The parameter location can be Query, Header, Path, or Body. In addition, static parameters are supported. Query is the query parameter following the URL. It starts with a question mark (?) and connects multiple parameters with &. Header is located in the request header and is used to transfer current information, for example, host and token. Path is a request parameter in the request path. If you configure a path parameter, you must also add this parameter to the request path. Body is a parameter in the request body and is generally in JSON format. Static is a static parameter that does not change with the value transferred by the API caller. It is supported only when Security Authentication is App authentication. The value of a static parameter is determined during API authorization. (If the parameter value is not set during authorization, the default value of the API input parameter is used when the API is called using an SDK, and an error is reported indicating that the static parameter value is missing when the API is called using an API tool.) The parameter type can be Number or String. Number corresponds to numeric data types such as int, double, and long. String corresponds to text data types such as char, vachar, and text. Whether the parameter is mandatory, whether a null value is allowed, and default value If the parameter is mandatory, it must be transferred for accessing the API. If this parameter is not mandatory and if it is not transferred during API access, the default value will be used. If the parameter is not transferred and no default value is available, null will be used if it is allowed and this parameter will be ignored if null is not allowed. NOTE: When defining an input parameter, ensure that the following size requirements are met: Query and Path: 32 KB. HEADER: The maximum size is 128 KB. BODY: The maximum size is 128 KB. You need to set input parameters based on the designed request parameters for the API workflow. For example, the request path of the API workflow used to query user information in multiple tables by user ID is /getUserInfo. You can configure input parameters as follows: If the request parameter for calling the API is id, and the information about the user with id needs to be returned through the API workflow , configure an input parameter as follows: Click Add and enter id for Name. Set Parameter Location to Query. Set Type to Number. Select Yes for Mandatory. Retain the default value. If the request parameters for calling the API are id1 and id2, and the user information between id1 and id2 needs to be returned through the API workflow, configure input parameters as follows: Click Add and enter id1 for Name. Set Parameter Location to Query. Set Type to Number. Select Yes for Mandatory. Retain the default value. Click Add again and configure parameter id2.