Generating an API Using Configuration

This topic describes how to generate an API using configuration.

Generating data APIs using configuration is simple. You do not need to write any code. Wizard mode is designed for users who do not have high requirements on API functions or have no experience in code development.

Prerequisites

You have configured data sources on the Data Connection Management page of Management Center.

Creating an API Directory

An API catalog is an API index that is orchestrated and recorded in a certain sequence. It is a tool for reflecting categories, guiding API usage, and searching for APIs, helping API developers effectively classify and manage API services.

On the DataArts Studio console, locate an instance and click Access. On the displayed page, locate a workspace and click DataArts DataService.

In the left navigation pane, choose an edition, for example, Exclusive Edition. The Overview page is displayed.
Choose API Development > API Catalogs and click .
In the dialog box displayed, enter an API catalog name, and click OK.
In the Operation column of an API catalog, edit or manage the API catalog.
Click Edit to the right of the API catalog that you want to edit. An API can be edited only when it is in the Created, Rejected, Offline, or Disabled state.

Configuring Basic API Information

On the DataArts Studio console, locate an instance and click Access. On the displayed page, locate a workspace and click DataArts DataService.

In the left navigation pane, choose an edition, for example, Exclusive Edition. The Overview page is displayed.

Choose API Development > APIs from the left navigation bar, and click Create. On the displayed page, enter the basic information.

**Table 1** API basic configuration
Parameter	Description
API	An API name consists of 3 to 64 characters and starts with a letter. Only letters, numbers, and underscores (_) are allowed.
API Catalog	A collection of APIs for a specific function or scenario. It is similar to a folder and specifies the location of APIs. You can search for APIs in a specified API catalog. The API catalog is the minimum organization unit of APIs in DataArts DataService and also the minimum management unit in the API gateway. Click Select Catalog to create an API catalog or select an existing one created in Creating an API Directory.
Request Path	API access path, for example, /v2/{project_id}/streams. 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.
Parameter Protocol	A protocol used to transmit requests. HTTP and HTTPS are supported. HTTP is a basic network transmission protocol. It is stateless, connectionless, simple, fast, and flexible, and uses plaintext for transmission. It is easy to use but has poor security. HTTPS 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. This method is used only for API registration. The POST request does not have a body. Instead, it involves transparent transmission.
Description	A brief description of the API to create.
Tag	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.
Reviewer	An owner who has permissions to review APIs. Click Add to enter the Review Center page. On the displayed page, click Add on the Reviewer Management tab page to add a reviewer.
Security Authentication	Security authentication mode, which can be: App Authentication: API Gateway authenticates API requests. This mode has the highest security level. IAM Authentication: IAM authenticates API requests. This mode has a medium security level. No authentication: No authentication is required for accessing the API. This mode has a low security level, and is not recommended.
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 Parameter	Configure parameters in the API request. An input parameter consists of the parameter location, parameter type, whether the parameter is mandatory, 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 passed by API callers. The parameter value is determined upon API authorization. If the parameter value is not set during authorization, the default value of the API input parameter is used. 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. Mandatory and Default Value: If you select Yes for Mandatory, parameters must be passed for accessing the API. Otherwise, the default value of the parameter will be used if the parameter is not passed for accessing the API. Constraints for the parameters are as follows: Query and Path: 32 KB. HEADER: The maximum size is 128 KB. BODY: The maximum size is 128 KB. For instance, to configure the dynamic parameter project_id in the /v2/{project_id}/streams request path, do as follows: Click Add and enter project_id for Name. Set Parameter Location to PATH. Set Type to STRING. Select Yes for Mandatory. Leave Default Value blank.

After the basic API information is complete, click Next to go to the Data Extract Logic page.

Configuring the Data Extraction Logic

Set Data Acquisition Method to GUI based.

Select a data source, data connection, database, and data table to obtain the tables to be configured.

For details on the data sources supported by DataArts DataService, see Data Sources. Configure data sources in Management Center in advance. You can search for a data table by name.
Configure parameter fields.
Click Add next to Parameter Settings. All fields in the table are displayed on the page for adding parameters. Select the request parameters, response parameters, and ranking parameters that you want to add to the corresponding lists.

Figure 2 Add Parameter dialog box

Edit request parameters.

A request parameter consists of a bound parameter, bound field, and operator. In the request parameter list, select a bound parameter and an operator.

The bound parameter is directly used to access APIs.
The bound field is the content that is accessed through an API call.

The operator determines how to process parameters in the access request. The following table lists the available operators.

**Table 2** Available operators
Operator	Description
=	Checks whether the values of two operands are the same. If yes, the condition is true.
<>	Checks whether the values of two operands are the same. If no, the condition is true.
>	Checks whether the value of the left operand is greater than that of the right operand. If yes, the condition is true.
>=	Checks whether the value of the left operand is greater than or equal to that of the right operand. If yes, the condition is true.
<	Checks whether the value of the left operand is less than that of the right operand. If yes, the condition is true.
<=	Checks whether the value of the left operand is less than or equal to that of the right operand. If yes, the condition is true.
%like%	Ignores the prefix and suffix in character matching.
%like	Ignores the prefix in character matching.
like%	Ignores the suffix in character matching.
in	Compares a value with a specified list of values.
not in	Compares a value with values not in a specified list. It is the opposite of the in operator.

Edit response parameters.
A response parameter consists of the parameter name, bound field, and parameter type.
- The parameter names are returned by the API.
- The bound fields are the actual content returned by the API.
- The parameter type is the data display format when the API is called, and can be a numeric or character.
Edit ranking parameters.
A ranking parameter consists of the parameter name, field name, whether the parameter is optional, and ranking mode.
- The parameter names are returned by the API.
- The field names are the content that is accessed when the API is called.
- Whether a ranking parameter is optional determines whether the ranking condition can be removed. If it is selected, the parameter is optional.
- The ranking mode can be ascending, descending, or custom.
Click the buttons in the Operation column to move up, down, or delete parameters.

Click Next and set the value of pre_order_by as the description of all ranking parameters and separate them with semicolons (;).

Data in Table 3 is used as an example.

**Table 3** Ranking parameters
Parameter	Description
id	a:asc a is the parameter name. asc indicates that parameters are listed in the ascending order.
name	b:asc b b:desc b is the parameter name. asc and desc indicate that parameters are listed in ascending and descending orders, respectively. The ranking order can be customized or left blank.
age	c:desc c is the parameter name. desc indicates that parameters are listed in the descending order.

Table 3 lists the ranking parameters. The following table describes how to configure pre_order_by.

**Table 4** Configuring parameter pre_order_by
Parameter	Backend Statement	Remarks
a:asc;b;c:desc	order by id ASC, name, age DESC	N/A
b;c:desc	order by name, age DESC	a is optional and can be left blank.
b:asc;c:desc	order by name ASC; age DESC	b can be customized. b can be listed in the ascending order.
b:desc;c:desc	order by name DESC; age DESC	b can be customized. b can be listed in the descending order.

Figure 3 Setting ranking parameters

pre_order_by is optional. If pre_order_by is not set, the mandatory fields are used as the ranking criterion.
If pre_order_by is set, configure an API following the parameter sequence. Example:
If pre_order_by is set to a:asc;b;c:desc, no error will be generated. If pre_order_by is set to b;a:asc;c:desc, errors will be reported.

Testing the API

After setting and saving all parameters, click Next.

Specify Value and click Debug. You can view the Request and Response details on the right part of the displayed page. If the test fails, follow the instructions as prompted and restart the test. During the configuration, pay attention to the settings of the normal response example.

After the test is complete, click OK.

Modifying the API

To modify an API, choose API Development > API Catalogs or API Development > APIs, locate the API, and click Edit to modify the API.

An API can be edited only when it is in the Created, Rejected, Offline, or Disabled state.

Parent topic: Creating an API

Previous topic: Creating an API

Next topic: Generating an API in the Script Mode