The data service module of Data Management (DMS) provides comprehensive capabilities to help you develop API operations with ease. This topic shows you how to create and manage API operations.

Prerequisites

API Gateway is activated.

Create an API operation

  1. Log on to the DMS console.
  2. In the top navigation bar, move the pointer over the More icon and choose Data Factory > Data Service.
  3. On the Data Service tab, click the API Development tab in the left-side navigation pane.
  4. Click New API in the upper-right corner. On the page that appears, define an API operation.
  5. Configure the properties as required. The properties of an API operation are divided into four parts and displayed on four tabs: AttributeConfiguration, ExecuteConfiguration, RequestParameters, and Return parameter.
    • On the AttributeConfiguration tab, configure the basic properties of an API operation. The following table describes the parameters.

      Parameter Description
      APIName Required. The name of the API operation. The name must be 4 to 100 characters in length and can contain letters, digits, and underscores (_). It must start with a letter.
      Description Optional. The description of the API operation. You can describe the logic of the API operation, such as the data to be returned and scenarios in which the API operation can be called.
      Path Required. The path that forms a part of the URL that is used to call the API operation. The URL is in the https://{Group domain name}{Path} format. Assume that the group domain name is xxxx-cn-hangzhou.alicloudapi.com and the path is defined as /item/monthly_data. In this case, the URL that is used to call the API operation is https://xxxx-cn-hangzhou.alicloudapi.com/item/monthly_data. The path must start with a forward slash (/) and can contain only letters, digits, underscores (_), and hyphens (-). Example: /item/add.
      ReturnFormat Required. The format of the data to be returned. Data can be returned only in the JSON format.
      RequestMode Required. The method to be used to call the API operation. Valid values: POST and GET.
      TimeOut (MS) Required. The maximum length of time during which a response to an API request must be received from the backend service of the called API operation. Unit: milliseconds. If the response time exceeds the specified time, API Gateway returns a timeout error. The maximum response time is 30,000 milliseconds, which equals 30 seconds.
      Returns the maximum number of records Required. The maximum number of records that can be returned for an API request. This parameter limits the number of records that can be returned for each query that is performed after you call the API operation. Assume that the instance to be queried is managed in Security Collaboration mode, and a maximum number of returned records is defined in a security rule of the instance. In this case, the maximum number of returned records for the API operation cannot exceed the maximum number of returned records that is defined in the security rule of the instance. Therefore, when you set this parameter, make sure that the value is smaller than the maximum number of returned records in the security rule.
    • On the ExecuteConfiguration tab, configure the properties of the API operation about data reading. The following table describes the parameters.
      Parameter Description
      Instance query type The type of instance query. Valid values: Single InstanceQuery and Cross-instanceQuery. If you set this parameter to Single InstanceQuery, the API operation can be called to read data from only one database instance. If you set this parameter to Cross-instanceQuery, you can write dynamic SQL statements for the API operation to query data across multiple database instances. Single-instance query allows you to define the API operation in table boot mode and script mode, whereas cross-instance query allows you to define the API operation only in script mode.
      Data source

      (This parameter is displayed only when you set the Instance query type parameter to Single InstanceQuery.)

      The database to be queried when the API operation is called. You can enter a keyword in the field to search for the databases that you have permissions to query.
      ConfigurationMode

      (This parameter is displayed only when you set the Instance query type parameter to Single InstanceQuery.)

      The method that is used to configure data query. Valid values: Table boot mode and Script mode. If you set this parameter to Table boot mode, you can configure data query by selecting a table and fields. If you set this parameter to Script mode, you must configure data query by defining variables and writing SQL statements. If you set the Instance query type parameter to Cross-instanceQuery, you can configure data query only in script mode.
      SelectTable

      (This parameter is displayed only when you set the Instance query type parameter to Single InstanceQuery.)

      The table to be queried. This parameter is displayed only when you set the ConfigurationMode parameter to Table boot mode. You can enter a keyword in the field to search for the table.
      FieldList

      (This parameter is displayed only when you set the Instance query type parameter to Single InstanceQuery.)

      The fields in the table. This section lists the fields in the table for you to define request parameters and response parameters. After you select a table, DMS automatically displays all the fields of the selected table. You can define fields as request parameters and response parameters by selecting the check boxes.
      Script mode

      (The ConfigurationMode parameter is displayed only when you set the Instance query type parameter to Single InstanceQuery.)

      The mode in which an SQL script is written to define the data query logic. When you switch from the table boot mode to the script mode, a message appears to remind you that the current definitions of request parameters and response parameters will be cleared.
      QuerySQL

      (This parameter is displayed only when you set the Instance query type parameter to Cross-instanceQuery or when you set the Instance query type parameter to Single InstanceQuery and the ConfigurationMode parameter to Script mode.)

      The SQL script to be defined for data query. When you set the ConfigurationMode parameter to Script mode, the QuerySQL field is displayed. You can write SQL statements for data query in the field. You can use the syntax that is supported by the selected database. If you set the Instance query type parameter to Cross-instanceQuery, only dynamic SQL syntax is supported. User-defined variables can be used in an SQL script. User-defined variables in an SQL script can be mapped to the request parameters of an API operation. Define variables in an SQL script in the ${Variable name} format. For example, you can use a variable named category in the following SQL statement: select item_id, item_name from ex_item where category=${category}. After you write the SQL script, click ParsingScript to check the validity of the SQL script and variables. After the script passes the check, DMS automatically uses the defined variables as the request parameters of the API operation.
    • On the RequestParameters tab, define the request parameters of the API operation. You can define request parameters by selecting fields in table boot mode or defining variables in script mode. The following table describes the properties of request parameters.
      Property Description
      ParametersName The name of the request parameter that is needed to call the API operation. The name must be 1 to 50 characters in length and can contain letters, digits, hyphens (-), and underscores (_). It must start with a letter or an underscore (_).
      VariableName or FieldName The source of the parameter. The value may be a field that you have selected in table boot mode or a variable that you have defined in script mode.
      Cannot be empty Specifies whether the request parameter is required for calling the API operation. In script mode, all request parameters are required. You cannot clear the check box. In table boot mode, you can decide whether a request parameter is required or optional. If you select the check box, the request parameter is required.
      Description The description of the request parameter.
      Data type The data type of the request parameter. Valid values: String, Integer, and Floating point. You can specify a proper data type to ensure that the data type of the request parameter is valid for the API operation to be called. This also ensures that the SQL statements for the API operation can be executed as required. Default value: String.
      Example value The sample value of the request parameter. Sample values that are provided in SDKs and documentation can help users call API operations.
      Default value The default value of the request parameter. If the request parameter is optional and its default value is specified, the default value is used when the API operation is called.
    • On the Return parameter tab, define the format of data to be returned after the API operation is called. API operations can be called only to read table data. Therefore, the response parameters also reflect the schema of the two-dimensional table to be queried. The following table describes the properties of response parameters.
      Property Description
      ParametersName The name of the response parameter. The name must be 1 to 50 characters in length and can contain letters, digits, hyphens (-), and underscores (_). It must start with a letter or an underscore (_).
      VariableName or FieldName The name of the field to be returned.
      Description The description of the response parameter.
      Data type The data type of the response parameter. Valid values: String, Integer, and Floating point. Queried data is converted based on the specified data type of the response parameter before the data is returned. Therefore, the data type of a response parameter affects the data to be returned in the JSON format.
      Example value The sample value of the response parameter. Sample values that are provided in SDKs and documentation can help users understand the information that is returned after API operations are called.
  6. Click Save. The API operation is created.
    Note You can click Publish to publish the API operation.

Publish an API operation

  1. Log on to the DMS console.
  2. In the top navigation bar, move the pointer over the More icon and choose Data Factory > Data Service.
  3. On the Data Service tab, click the API Development tab in the left-side navigation pane.
  4. On the APIManagement page, find the API operation of which the value in the PublishStatus column is Not published and click Publish in the Operation column.
    Note You can also click Publish on the editing page of the API operation to publish the API operation.
  5. In the message that appears, click OK.
    After an API operation is published, you can use an SDK to call the API operation. The data service module of DMS is integrated with API Gateway. Therefore, you can view published API operations in the API Gateway console but you cannot edit them. Otherwise, the API operations may become unavailable.

Manage an API operation

  1. Log on to the DMS console.
  2. In the top navigation bar, move the pointer over the More icon and choose Data Factory > Data Service.
  3. On the Data Service tab, click the API Development tab in the left-side navigation pane.
    • Modify an API operation
      1. On the APIManagement page, find the API operation that you want to modify and click Modify in the Operation column.

        On the page that appears, modify the API operation. The configuration rules for modifying an API operation are the same as those for creating an API operation. For more information, see Create an API operation.

        Note
        • You can modify all properties of an API operation. However, make sure that the modification does not affect the online applications that are calling this API operation. Changes to request parameters or response parameters may affect the calling of an API operation. This is because changes to request parameters or response parameters may change the logic of the API operation.
        • You must republish the modified API operation to make the modification take effect.
    • Delete an API operation
      1. On the APIManagement page, find the API operation that you want to delete and click Delete in the Operation column.
      2. In the message that appears, click OK. The API operation is deleted.

        After an API operation is deleted from DMS, the API operation is also unpublished and deleted from API Gateway.