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

Prerequisites

API Gateway is activated.

Create an API

  1. Log on to the DMS console V5.0.
    Note To switch to the previous version of the DMS console, click the 5租户头像 icon in the lower-right corner of the page. For more information, see Switch to the previous version of the DMS console.
  2. In the top navigation bar, click DTS. In the left-side navigation pane, choose Data Application > Data Service.
    Note If you are using the previous version of the DMS console, move the pointer over the More icon in the top navigation bar and choose Data Factory > Data Service.
  3. In the left-side pane, click the API Development tab.
  4. Click New API in the upper-right corner. On the page that appears, define an API.
  5. Configure the properties as required.

    The properties of an API 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. The following table describes the properties.

      Property Description
      APIName Required. The name of the API. 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. You can describe the logic of the API, such as the data to be returned and scenarios in which the API can be called.
      Path Required. The path that forms a part of the URL that is used to call the API.

      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.

      If the path is defined as /item/test and the group domain name is xxxx-cn-hangzhou.alicloudapi.com, the URL that is used to call the API 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. 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. Unit: milliseconds. Default value: 10000.

      If the response time exceeds the specified time, API Gateway returns a timeout error. Maximum value: 30000, which indicates 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 The instance to be queried is managed in Security Collaboration mode, and the maximum number of returned records is defined in a security rule of the database instance. In this case, the maximum number of returned records for the API 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 for data reading. The following table describes the properties.
      Property 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 can be defined in table boot mode or script mode.
      • Cross-instanceQuery: You can write dynamic SQL statements for the API to query data across multiple database instances. In this case, the API can be defined only in script mode.
      Data source The database to be queried when the API 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. You can select a table in 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. 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.

      This parameter is displayed only in the following two scenarios:
      • The Instance query type parameter is set to Cross-instanceQuery. 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. 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. 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. 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 to be called. This also ensures that the SQL statements for the API 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 you call APIs.

      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 is called.
    • On the Return parameter tab, define the format of the data to be returned after the API is called. APIs 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, 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, the queried data is converted to 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 you understand the information that is returned after APIs are called.
  6. Click Save. The API is created.
    Note You can click Publish to publish the API.

Publish an API

  1. Log on to the DMS console V5.0.
    Note To switch to the previous version of the DMS console, click the 5租户头像 icon in the lower-right corner of the page. For more information, see Switch to the previous version of the DMS console.
  2. In the top navigation bar, click DTS. In the left-side navigation pane, choose Data Application > Data Service.
    Note If you are using the previous version of the DMS console, move the pointer over the More icon in the top navigation bar and choose Data Factory > Data Service.
  3. In the left-side pane, click the API Development tab.
  4. On the APIManagement page, find the API whose 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 to publish the API.
  5. In the message that appears, click OK.
    After an API is published, you can use an SDK to call the API. The data service module of DMS is integrated with API Gateway. Therefore, you can view published APIs in the API Gateway console but you cannot edit them. Otherwise, the APIs may become unavailable.

Manage an API

  1. Log on to the DMS console V5.0.
    Note To switch to the previous version of the DMS console, click the 5租户头像 icon in the lower-right corner of the page. For more information, see Switch to the previous version of the DMS console.
  2. In the top navigation bar, click DTS. In the left-side navigation pane, choose Data Application > Data Service.
    Note If you are using the previous version of the DMS console, move the pointer over the More icon in the top navigation bar and choose Data Factory > Data Service.
  3. In the left-side pane, click the API Development tab.
    • Modify an API
      1. On the APIManagement page, find the API that you want to modify and click Modify in the Operation column.

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

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

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