Developing APIs

• In the navigation pane, choose API Catalog and click Create API.
• In the navigation pane, choose API Management and click Create.

• API: An API name consists of 3 to 64 characters and starts with a letter. Only letters, numbers, and underscores (_) are allowed.

  TestScore is used as an example.

• Request Path: path for accessing the API. The request path is the part after the domain name and before the query parameters in a URL.

  /TestScore is used as an example.

• Protocol: protocol used to transmit requests. The exclusive edition supports HTTPS.

  HTTPS is used as an example.

• Request Method: type of the requested operation, such as GET and POST. The method complies with the RESTful style.

  GET is used as an example.

• Security Authentication: When creating an API, you can select App authentication, IAM authentication, or Non-authentication. The 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 is used as an example.

• Input Parameters: parameters required for calling the API. The parameters are used as the request parameters on the Set Data Extract Logic page. An input parameter consists of the parameter name, location, type, whether the parameter is mandatory, whether a null value is allowed, and the default value.

  In this example, you want to query the score of an examinee and whether the examinee passed the exam. You need to input the admission card No. and pass score.

  Configure two input parameters: Number and Score.

  1. Click Add and enter Number and Score for Name.
  2. Set Parameter Location to Query.
  3. For the Number parameter, set Type to String. For the Score parameter, set Type to Number.
  4. To ensure the scalability of the API query capability, select No for Mandatory.
  5. Retain the default values for other parameters.
  Figure 1 Basic configuration
  

1. Configuring the Data Obtaining Method
   The data obtaining mode can be configuration mode, script mode, or MyBatis mode.

   • Configuration mode: Data APIs are easy to use. You do not need to write any code. You can select and configure data APIs on the product page to quickly generate APIs. Wizard mode is designed for users who do not have high requirements on API functions or have no experience in code development.
   • Script/MyBatis mode: This mode can meet the personalized query requirements of advanced users. Users can compile API query SQL statements and support multi-table association, complex query conditions, and aggregation functions. For details, see Generating an API Using a Script or MyBatis.

   The configuration mode is used as an example.

2. Configuring Data Connections

   Configure the data source type, data connection, database, and data table.

   In this example, select the Hive data source type, the MRS Hive connection created in the management center, and the prepared database and data table.

   Figure 2 Configuring Link Parameters
   

3. Configuring Parameter Fields

   Click Add next to Parameter Setting. 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.

   In this example, you want to query the score of a specific examinee and check whether the examinee passed the exam. Select the Number and Score fields for Request Parameter, and select all fields for Response Parameter. As you want to sort the examinees who passed the exam by score, select the Score field for Ranking Parameters.

   Figure 3 Add Parameter dialog box
   

4. 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.

   • Bound parameters are available to external systems. They are the input parameters defined on the Configure Basic Details page and are directly used to access the API.
   • Bound fields are invisible to external systems. They are fields of the selected tables and are accessed during an API call.
   • Operators determine how bound fields and parameters in access requests are processed. For details about the supported operators and their meanings, see Table 2.
   In this example, select Score and Number for Binding parameter. Select the Score field for Bound Parameter and select the >= operator to query whether the examinee passed the exam. Select the Number field for Bound Parameter and select the = operator to query the score of the examinee.

   Figure 4 Parameters
   

5. Edit the returned parameter information.

   A response parameter consists of the parameter name, bound field, and parameter type.

   • Parameters are available to external systems and can be customized. They are returned to API callers.
   • Bound fields are invisible to external systems. They are fields of the selected tables and are returned during an API call.
   • The parameter type is the data display format when the API is called, and can be a numeric or character.
   In this example, the Score parameter is of the numeric type. Set the parameter type to NUMBER. Retain STRING for other parameters.

   Figure 5 Response parameters
   

6. Edit the sorting parameters.

   A ranking parameter consists of the parameter name, field name, whether the parameter is optional, and ranking mode. Multiple ranking parameters are allowed.

   • Parameter names can be customized and associated with field names.
   • Field names are invisible to external systems. They are fields of the selected tables and are accessed during an API call.
   • Optional determines whether the ranking parameter is mandatory for API calling.
   • The ranking mode can be ascending, descending, or custom.
   • If there are multiple ranking parameters, when the first ranking parameter is the same, the subsequent parameters are used for ranking.

   In this example, set Parameter to score and Ranking Mode to Descending, and select Optional.

   Figure 6 Ranking parameter
   

7. (Optional) Configure the total number of returned records.

   You can enable Return Total Records in DataArts DataService Exclusive Edition. Then the total number of script execution results will be returned.

   In this example, the total number of returned records is not configured. The switch is turned off.

1. Set the input parameter and adjust the value of pre_order_by.

   In this example, you can refer to the following configuration to test the API:

   • Querying the scores of all examinees in the English exam does not require parameters.
   • To query the score of a specific examinee, select the Transfer Value check box following the Number parameter, and enter an actual admission ticket number in the data table.
   • To query whether an examinee passed the English exam, select the Transfer Value check box following the Number parameter, and enter an actual admission ticket number in the data table. Select the Transfer Value check box following the Score parameter, and enter the pass score (such as 425) for the Score parameter.
   • To query the examinees who passed the English exam, select the Transfer Value check box following the Score parameter, and enter the pass score (such as 425) for the Score parameter.
   • To sort the examinees who passed the English exam in descending order of scores, select the Transfer Value check box following the Score parameter, and enter the pass score (such as 425) for the Score parameter. Select the Transfer Value check box following the pre_order_by parameter, and retain the default descending order of values.
2. (Optional) Change the values of pagination parameters.

   The system pages the returned data. During API debugging, the default page size is 100, and data on the first page is returned.

   In this example, the default value is used, that is, 100 records on the first page of the data table are returned.

   Figure 7 Setting parameters
   

In the cluster list, select the prepared cluster and click Connectivity Test. If a message is displayed indicating that the connection is successful, the cluster is available. If no cluster is available, prepare a cluster by referring to the Managing Exclusive Clusters section.

• Querying the scores of all examinees in the English exam: The first 100 examinees on the first page are returned.
• Querying the score of a specific examinee in the English exam: The score and personal information of the examinee are returned.
• Querying whether a specific examinee passed the English exam: If none is returned, the examinee failed the exam. If the score and personal information of the examinee are returned, the examinee passed the exam.
• Querying the list of examinees who passed the English exam: The first 100 examinees who passed the exam on the first page are returned.
• Sorting the examinees who passed the English exam by score: The first 100 examinees who passed the exam are returned in descending order of score.

Figure 8 Testing the API

• If you are only a developer, contact the reviewer to review the API. After the API creation application is approved, the API is successfully created.
• If you are both a developer and a reviewer, skip this step.
  

  APIs must be reviewed and approved before they can be published. APIs are reviewed in the following way:

  • An API publisher who does not have the reviewer permission must submit the API to the reviewer for review.
  • An API publisher who has the reviewer permission can publish an API without review or approval.
  • If you are not a developer but only a reviewer, go to Review Center to review your API request.