All Products
Search
Document Center

Develop an API operation

Last Updated: Jul 27, 2020

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

Create an API operation

  1. Log on to the DMS console.

  2. In the top navigation bar, choose Data Factory > Data Service.

  3. On the Data Service page, click API Development in the left-side navigation pane.

  4. Click New API in the upper-right corner. On the page that appears, define an API operation.
    Data Service API Development1

  5. Complete the configuration information according to the following tables.
    Properties of an API operation are divided into four parts and displayed on four tabs, including AttributeConfiguration, ExecuteConfiguration, RequestParameters, and Return parameter.

    • On the AttributeConfiguration tab, set 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 logic of the API operation, including the data to be returned and the scenarios where the API operation can be used.
      Path (Required) The path that forms a part of the URL used to call the API operation. The URL used to call an API operation is in the format of https://{Group domain name}{Path}. For example, if the group domain name is xxxx-cn-hangzhou.alicloudapi.com and the path is defined as /item/monthly_data, the URL 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 only contain letters, digits, underscores (), and hyphens (-). For example, a path can be /item/add.
      ReturnFormat (Required) The format of returned data. Currently, data can only be returned in the JSON format.
      RequestMode (Required) The method of calling the API operation. The following two general request methods are supported: POST and GET.
      TimeOut (MS) (Required) The maximum length of time during which an API request must receive a response from the backend service of the called API operation. Unit: milliseconds.
      If the response time exceeds this value, API Gateway abandons the request and returns the corresponding error message to the user. This value cannot exceed 30,000 milliseconds, that is, 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 SQL query performed by calling the API operation. Note that if the instance to be queried is managed in the Secure Collaboration mode and a maximum number of returned records has already been defined in a security rule of the instance, the maximum number of returned records defined in the API operation cannot exceed the maximum number of returned records defined in the security rule of the instance. Therefore, when you set this parameter, make sure the value is smaller than the maximum number of returned records defined in the security rule.
    • On the ExecuteConfiguration tab, configure data reading for the API operation. 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 select Single InstanceQuery, the API operation reads data from only one database instance when being called. If you select Cross-instanceQuery, you can write DSQL statements in the API operation to query data across multiple instances. In addition, single-instance query allows you to define the API operation in the table-based wizard mode, while cross-instance query only allows you to define the API operation in the script mode.
      Data source (Available after you select Single InstanceQuery) The database to be queried when the API operation is called. Only databases on which you have the permission to query will appear in the drop-down list. You can select a database from the drop-down list, or enter a keyword and select a database from the dynamically matched result.
      ConfigurationMode (Available after you select Single InstanceQuery) The method of configuring data query. Valid values: Table boot mode and Script mode. If you select Table boot mode, you can quickly configure data query by selecting a table and fields. If you select Script mode, you need to configure data query by defining variables and writing SQL scripts. If you set Instance query type to Cross-instanceQuery, you can only configure data query in the script mode.
      SelectTable (Available after you select Single InstanceQuery) The table to be queried. This parameter is available if you set ConfigurationMode to Table boot mode. You can select a table from the drop-down list or enter a keyword and select a table from the dynamically matched result.
      FieldList (Available after you select Single InstanceQuery) The fields in the table. This section lists the fields in the table for you to quickly define request parameters and response parameters. After you select a table, the system automatically displays all the fields of the selected table. You can select fields as request parameters and response parameters by selecting the check boxes.
      Script mode (Available after you select Single InstanceQuery and Script mode) In the script mode, you need to define the data query logic by writing scripts. Note that when you switch from the table-based wizard mode to the script mode, the system prompts you for the current definitions of request parameters and response parameters.
      QuerySQL (Available after you select Cross-instanceQuery or after you select Single InstanceQuery and Script mode) The SQL script to be defined for data query. You can write SQL statements for data query in this input box. You can use the syntax supported by the selected data source. If you set Instance query type to Cross-instanceQuery, only DSQL syntax is supported.
      User-defined variables can be used in SQL scripts. User-defined variables in SQL scripts can be mapped to request parameters of an API operation.
      Variables are used in SQL scripts 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 finish writing the SQL script, click ParsingScript to check whether the script is correctly written and variables correctly defined. After the script passes the check, the system automatically uses the defined variables as the request parameters of the API operation.

      Data Service API Development2Data Service API Development3

    • On the RequestParameters tab, define input parameters of the API operation. You can define input parameters by selecting fields in the table-based wizard mode or defining variables in the script mode. The following table describes the properties of request parameters.

      PropertyDescription
      ParametersNameThe name of the input parameter that is needed to call the API operation. The input parameter 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 FieldNameThe source of the parameter. The value may be a field you selected in the table-based wizard mode or a variable you defined in the script mode.
      Cannot be emptySpecifies whether the request parameter is required for calling the API operation. In the script mode, all request parameters are required. That is, you cannot clear the check box. In the table-based wizard mode, you can decide whether a request parameter is required or optional. If you select the check box, the request parameter is required.
      DescriptionThe description of the request parameter.
      Data typeThe data type of the request parameter. Valid values: String, Integer, and Float. The value of the request parameter must match the corresponding data type. The data type of the request parameter affects the SQL script in the API operation. The default data type is String.
      Example valueThe sample value of the request parameter. Sample values provided in SDKs and documents about API operations can help users correctly call the API operations.
      Default valueThe default value of the request parameter. If the request parameter is optional and its default value is specified, the default value will be used when the API operation is called.

      Data Service API Development4

    • On the Return parameter tab, define the format of data to be returned after the API operation is called. Currently, API operations can only be called to read table data. Therefore, response parameters also reflect the schema of the two-dimensional table that is queried. The following table describes the properties of response parameters.

      Property Description
      ParametersName The name of the response parameter. The response parameter 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 Float. Queried data is converted according to the data type of the response parameter before being returned. Therefore, the data type of a response parameter affects the data returned in the JSON format.
      Example value The sample value of the response parameter. Sample values provided in SDKs and documents about API operations can help users correctly understand returned information after the API operations are called.

      Data Service API Development5

  6. Click Save to finish defining the API operation.

    Click Publish. The API operation you just defined will be immediately published.

Publish an API operation

  1. Log on to the DMS console.

  2. In the top navigation bar, choose Data Factory > Data Service.

  3. On the Data Service page, click API Development in the left-side navigation pane.

  4. On the APIManagement page, find an API operation whose value of the PublishStatus field is Not published, and click Publish in the Operation column.
    Data Service API Development6

    You can also go to the editing page of the API operation, and click Publish to publish the API operation.

  5. In the message that appears, click OK.

After an API operation is published, it can be called by using the SDK downloaded from API Gateway. Because the data service feature of DMS is integrated with API Gateway, you can view published API operations in the API Gateway console but you cannot edit them. Otherwise, the API operation may become unavailable.

Modify an API operation

  1. Log on to the DMS console.
  2. In the top navigation bar, choose Data Factory > Data Service.
  3. On the Data Service page, click API Development in the left-side navigation pane.
  4. On the APIManagement page, find the target API operation and click Modify in the Operation column.
  5. On the page that appears, modify the API operation. The configuration rules of modifying an API operation are the same as those of creating an API operation. For more information, see Create an API operation.

Note:

  • All properties of an API operation can be modified, but make sure that modification of an API operation does not affect the online applications that are calling this API operation. Changes to request parameters or response parameters may affect the calling of API operations. This is because changes to request parameters or response parameters will change the logic of the corresponding API operation.
  • Changes to an API operation will take effect only after you republish the modified API operation.

Delete an API operation

  1. Log on to the DMS console.
  2. In the top navigation bar, choose Data Factory > Data Service.
  3. On the Data Service page, click API Development in the left-side navigation pane.
  4. On the APIManagement page, find the target API operation and click Delete in the Operation column.
  5. In the message that appears, click OK. The API operation will be immediately deleted.

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