Dataphin:Test and publish API

Prerequisites

You need to create an API before you begin. For more information, see Create an API.

Description of API call/test direct connection mode and proxy mode

DataService Studio supports direct connection mode and proxy mode for calling APIs. If an API is associated with row-level permissions, the authentication method is determined by the calling mode.

• Direct connection mode: Apply for row-level permissions for the DataService Studio application in row-level permissions, and use the application for authentication.

• Proxy mode: If an application needs to call an API with a user's row-level permissions, you need to apply for row-level permissions for the DataService Studio application in row-level permissions, and then apply for proxy permissions for the API for the application, which allows it to call the API on behalf of the user.

Operations in the top area of the API test page

• View Domain Name: You can view the domain name at the top of the page. This domain name is used only for internal testing. For the domain name used for client calls, see View domain name.

• Switch API: You can switch to view submitted or published APIs in the upper-left corner of the page. You can search for APIs by name or ID using fuzzy search, and switch to APIs that you have permissions to access in the current service project. The system recommends the nine most recent APIs that you have accessed (including viewing, editing, testing, and adding) in the current project.

• Switch API Runtime Environment: You can switch the API runtime environment for API testing. When the runtime environment is the development environment, the development data source is used for testing. When the runtime environment is the production environment, the production data source is used for testing. If the API is not published, you cannot switch to the production environment for testing.

  Note

  If the API is in Basic mode and the runtime environment is the development environment, the production data source is used for testing the API.

• Switch API Version: You can switch versions for testing in the upper-right corner of the test page. When the runtime environment is the development environment, you can select a submitted version. When the runtime environment is the production environment, you can select a published version.

Step 1: Test the API

1. On the Dataphin home page, choose Service > API Development from the top menu bar.

2. Select a service project in the upper-left corner, and then choose API Service > API in the navigation pane on the left to go to the API page.

   • On the API page, click the Test icon in the Actions column of the target API to go to the API test page.

   • On the API page, click More-Version Management in the Actions column of the target API to open the Version Management panel, and then click Test in the operation column of the target API to go to the API test page.

3. On the API Test page, you can enter parameter values to verify whether the returned parameters meet your expectations.

   1. Configure the parameters in the Business Request Parameter List section.

      • If the operation type is GET or LIST, set the Test Input Value to the field values from your business data. The parameters listed are the request parameters that you configured when you created the API.

      • If the operation type is Create, Update, or Delete, the fields listed are the request parameters that you configured when you created the API. You can add, copy, or delete parameters as described below.

        • Add Parameter Item: Click Add Parameter Item and enter parameter values as prompted. You can add data entries up to the maximum input limit of the API.

        • Batch Add: Click Batch Add. In the Batch Add Business Request Parameters dialog box, enter parameter instance values. Separate each parameter set with a new line. You can specify separators and text qualifiers for the parameters.

          • Separator: The character used to separate fields. You can use a comma (,), semicolon (;), vertical bar (|), tab character (\t), or a custom separator. Custom separators can contain multiple characters.

          • Text Qualifier: The character used to enclose text fields. The supported options are None, double quotation marks (""), and single quotation marks ('').

        • Full Screen Input: Click Full Screen Input. Then, click Add 1 Parameter Item Row, Add 5 Parameter Item Rows, or Add 10 Parameter Item Rows at the bottom of the page to quickly add rows.

        • Copy: Click the Copy icon in the Actions column. The system clones the parameter values of the current row and adds them as a new row at the bottom of the list.

        • Delete: Click the Delete icon in the Actions column to delete a single row. To delete multiple rows, select the parameters from the list and click Batch Delete at the bottom.

   2. Configure the parameters in the Common Request Parameter List section.

      • If the API is a direct connection data source API (query type) or a service unit API, the system displays parameters, such as PageStart, PageSize, and OrderByList, based on the API request method.

        • If paged query is enabled and the API operation type is LIST, the PageStart, PageSize, and OrderByList parameters are displayed. If the API operation type is GET, the OrderByList parameter is displayed.

        • If paged query is disabled and the API operation type is LIST, the OrderByList parameter is displayed. You can clear the Hide Parameters checkbox to display the PageSize and OrderByList parameters.

      • If the API is a direct connection data source API (query type), a service unit API, or a composite API, and associated row-level permissions are enabled, the AccountType and DelegationUid parameters are displayed.

      • If the API is a direct connection data source API (operation type), only the ApiVersion parameter is displayed.

        Note

        When you test an API, the input parameter cannot exceed 1,000 characters. If you call the API directly, there is no character limit.

        Parameter	Description	Test input value
        AccountType	When using proxy mode authentication, you need to specify the account type of the proxy user. ACCOUNT_NAME: Dataphin username. USER_ID: Dataphin internal unique ID. SOURCE_USER_ID: Source system account ID. Note This parameter needs to be configured only when DelegationUid is set. If this parameter is not filled in, the default type is USER_ID.	Select the account type of the proxy user. You can select ACCOUNT_NAME, USER_ID, or SOURCE_USER_ID.
        DelegationUid	The user being proxied for access. You need to pass in the corresponding account ID based on the selected AccountType. After setting this parameter, the proxy mode authentication method is used.	Only the current tenant account is supported as DelegationUid.
        ApiVersion	Specifies the version of the API to call. The latest version is used by default.	The test input value is obtained by switching versions in the upper-right corner of the page. Note When the runtime environment is the development environment, the apiVersion parameter is supported, and you can only select submitted APIs for calling.
        PageStart	Defines which record to start displaying the returned data from.	Configure a positive integer, such as 2.
        PageSize	Defines how many records to return per page.	Configure a positive integer, such as 56.
        OrderByList	Defines the sorting method for multiple returned parameters. If not specified, ascending order is used by default.	The test input value needs to be obtained from the Business Request Parameter List.
        ReturnTotalNum	Specifies whether to return the total number of rows in the result. If you set ReturnTotalNum=true, the total number of rows is returned. This may affect performance.	This parameter is displayed if the API operation type is List and paged query is enabled. Set this parameter to a positive integer, such as 1000.

   3. If the API is a direct connection data source API (query type), a service unit API, or a composite API, and associated row-level permissions are enabled, the Row-Level Permission List section displays information about the enabled row-level permissions associated with the current API version and environment. This information includes the row-level permission name and description.

   4. In the Optional Return Parameter List section, select the return parameters. The list of return parameters corresponds to the API return parameters of the selected API version.

      • If the operation type is GET or LIST, you must select at least one return parameter to test the API.

      • If the operation type is Create, Update, or Delete, all parameters are selected by default and cannot be deselected.

   5. Configure the protocol and return count for the API.

      Parameter	Description
      Protocol	If you configured the API to support both HTTP and HTTPS, you can select which protocol to use for the test.
      Return Count	Specifies the number of records to return when you test the API: If the request method is LIST, you can select Return Count to return up to 10,000 records. You cannot modify Return Count for GET requests.

4. After the configuration is complete, click Debug/Test after the return count to test the connectivity between the API and the data source data.

   • When you test the API, you can click View Script to view the SQL script. This helps you check whether the query results match the script's expectations.

     Note

     • You cannot view the script if the registered API or model API does not have a script.

     • When you call a composite API, if a referenced API has row-level permission controls, you must pass the AccountType and DelegationUid parameters to the referenced API.

     • To call a combination API using proxy mode, you only need to apply for proxy permissions for the combination API.

   • If the API call mode is asynchronous mode, after the API is tested/debugged, the query results will be displayed in the test results area. You can view your execution results, logs, code, and other information in the test results. For the asynchronous query process, see Asynchronous invocation process description.

     • View request results: Click the Call API tab, then click the Return Result tab to view the request results returned in the API call body.

     • Script code: Click the Call API tab, then click the Script Code tab to view the written SQL statement.

     • View logs: Click the Get Query Status tab to view the execution logs of the API call. To cancel the API test/debug, you can click Cancel Query to cancel the query request.

     • View query results: Click the Get Query Results tab to view the final query results returned in the API call body.

5. In the Return Result/Test Result section, view the test results.

   If the test fails, you can refer to Appendix: Error codes and solutions.

6. This operation is supported only when testing the API. Click the API Authorization button at the bottom to authorize the API to applications. For more information, see DataService Studio permission management.

Step 2: Publish the API

After this, business application users can query and request permissions to call the API in the DataService Studio overview page.

Appendix: Error codes and solutions