All Products
Search

This Product

    DataWorks:Best practice: Specify an API request parameter as an optional parameter

    Document Center

    DataWorks:Best practice: Specify an API request parameter as an optional parameter

    Last Updated:Nov 08, 2024

    When you encapsulate an API by using a data source, you can specify one or more request parameters of the API as optional parameters based on your business requirements. After you specify a request parameter of the API as an optional parameter, the caller can choose whether to specify a value for the request parameter when the caller call the API. This enables more flexible API-based queries. This topic describes how to use the codeless user interface (UI) or code editor to specify a request parameter of an API as an optional parameter.

    Background information

    In this example, the ods_user_info_d user information table is used. The following description provides the schema of the table.

    Field name

    Data type

    Description

    uid

    INT

    The ID of the user.

    gender

    STRING

    The gender of the user.

    age_range

    STRING

    The age of the user.

    zodiac

    STRING

    The zodiac sign of the user.

    In this example, the uid field is specified as a required request parameter, and the gender field is specified as an optional request parameter.

    Codeless UI

    1. Go to the DataService Studio page.

    2. In the Service Development panel, move the pointer over the Add icon and choose Create API > Generate API.

    3. In the Generate API dialog box, set API Mode to Wizard Mode and configure other parameters based on your business requirements. Then, click OK.

      For more information about the parameters, see Create an API by using the codeless UI.

    4. In the Select Table section of the configuration tab that appears, configure the parameters.

    5. In the Select Parameters section, select fields that you want to use as request parameters.

      Select Parameters section

    6. In the right-side navigation pane of the configuration tab, click Request Param.

      Then, you can configure the Required parameter for fields displayed in the Request Param panel, as shown in the following figure.Request Param

      • If you select Required for a field, the field is a required request parameter. In this case, you must specify a value for the request parameter when you call the current API. Otherwise, the system reports a parameter verification exception, and the API call fails.

      • If you do not select Required for a field, the field is an optional request parameter. In this case, you can specify a value for the request parameter or leave the request parameter empty when you call the current API. If you leave the request parameter empty when you call the current API, the request parameter is not used as a query condition.

    7. Call the API.

      • Case 1: Specify a value for each of the uid and gender request parameters. The following code shows the query request:

        SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
WHERE uid = 0016359810821
AND gender = 'female';

      • Case 2: Specify a value for the uid request parameter and leave the gender request parameter empty. The following code shows the query request:

        SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
WHERE uid = 0016359810821;

    Code editor

    Note

    • The Basic SQL mode cannot implement the logic of optional request parameters. If you set SQL Mode to Basic SQL in the Generate API dialog box of an API and clear the Required check box for a field (request parameter) in the Request Param panel of the API, the following situations may occur:

      • If you specify a value for the request parameter when you call the API, the request parameter is displayed in the following format in the query request: Request parameter = Specified value.

      • If you do not specify a value for the request parameter when you call the API, the request parameter is displayed in the following format in the query request: Request parameter = null.

    • If you want to implement the logic of optional request parameters, use the Advanced SQL mode for an API. This indicates that you must set SQL Mode to Advanced SQL in the Generate API dialog box of the API.

    1. Go to the DataService Studio page.

    2. In the Service Development panel, move the pointer over the Add icon and choose Create API > Generate API.

    3. In the Generate API dialog box, set API Mode to Script Mode and configure other parameters based on your business requirements. Then, click Determine.

      For more information about the parameters, see Create an API by using the code editor.

    4. In the Select Table section of the configuration tab that appears, configure the parameters.

    5. In the Edit Query SQL section, write an SQL statement with MyBatis tags to configure request parameters. The following code provides an example:

      SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
<where>
    <if test='gender!=null'>
    gender = ${gender}
    </if>
    and uid = ${uid}
</where>

    6. In the right-side navigation pane of the configuration tab, click Request Param.

      Then, you can configure the Required parameter for fields displayed in the Request Param panel, as shown in the following figure.Request Param

    7. Call the API.

      • Case 1: Specify a value for each of the uid and gender request parameters. The following code shows the query request:

        SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
WHERE uid = 0016359810821
AND gender = 'female';

      • Case 2: Specify a value for the uid request parameter and leave the gender request parameter empty. The following code shows the query request:

        SELECT uid, gender, age_range, zodiac
FROM ods_user_info_d
WHERE uid = 0016359810821;