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. In the left-side navigation pane, click the API Development tab.
  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 path must start with a forward slash (/) and can contain only letters, digits, underscores (_), and hyphens (-). Example: /item/add.

      The URL is in the https://{Group domain name}{Path} format.

      Assume that the path is defined as /item/test and the group domain name is xxxx-cn-hangzhou.alicloudapi.com. In this case, the URL that is used to call the API operation is https://xxxx-cn-hangzhou.alicloudapi.com/item/test.

      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
      • GET
      In this example, the RequestMode parameter is set to 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. Default value: 10000.

      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. Default value: 1000.
      Note 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.
    • 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: You can query data only in one database instance. In this case, the API operation can be defined in table boot mode or script mode.
      • Cross-instanceQuery: You can write dynamic SQL statements for the API operation to query data across multiple database instances. In this case, the API operation can be defined only in script mode.
      Data source 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.

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

      ConfigurationMode The method that is used to configure data query. Valid values:
      • Table boot mode: You can configure data query by selecting a table and fields.
      • Script mode: You can configure data query by writing SQL statements and defining variables.
      Note 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.

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

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

      This parameter is displayed only when you set the ConfigurationMode parameter to Table boot mode.

      FieldList The fields in the table. This section lists all of the fields in the selected table for you to define request parameters and response parameters. You can define fields as request parameters and response parameters by selecting the check boxes.

      This parameter is displayed only when you set the ConfigurationMode parameter to Table boot mode.

      QuerySQL The SQL script to be used for data query. You can write SQL statements for data query in the field.

      User-defined variables can be used in the SQL script and mapped to the request parameters of the API operation. Define the variables in the 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.

      This parameter is displayed only in the following two scenarios:
      • The Instance query type parameter is set to Cross-instance query. In this case, only dynamic SQL statements are supported.
      • The Instance query type parameter is set to Single InstanceQuery and the ConfigurationMode parameter is set to Script mode. In this case, make sure that the SQL syntax is the same as that for the database that you selected.
    • 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, underscores (_), and hyphens (-). 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. If you select the check box, the request parameter is required.
      Note If you set the ConfigurationMode parameter to Script mode, all request parameters are required. You cannot clear the check box. If you set the ConfigurationMode parameter to Table boot mode, you can decide whether a request parameter is required or optional.
      Description The description of the request parameter.
      Data type The data type of the request parameter. Valid values: String, Integer, and Floating point. Default value: String.

      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.

      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 request 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, underscores (_), and hyphens (-). 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. Default value: String.

      After you specify a proper data type for the response parameter, queried data is converted based on the specified data type and is 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. In the left-side navigation pane, click the API Development tab.
  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. In the left-side navigation pane, click the API Development tab.
    • 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.