Dataphin:Test and publish an API

Prerequisites

Before you begin, make sure that you have created an API. For more information, see Create an API.

Direct connection and proxy modes for API calls and tests

Data Service supports calling APIs in direct connection mode and proxy mode. If an API is associated with row-level permissions, the authentication method depends on the call mode.

• Direct connection mode: Request row-level permissions for the DataService Studio application in the row-level permissions settings. The application is used for authentication.

• Proxy mode: If an application needs to call an API using the user's row-level permissions as a proxy, request row-level permissions for the DataService Studio application. Then, request proxy permissions for the application to call the API. This lets the application 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 for internal testing only. For the domain name used for client calls, see View domain names.

• Switch APIs: In the upper-left corner of the page, you can switch to view submitted or published APIs. You can perform a fuzzy search for an API by its name or ID. The search includes all APIs you have permission to access in the current service project. The system recommends the last nine APIs you have accessed (viewed, edited, tested, or created) in the current project.

• Switch API running environments: You can switch the running environment to test the API. When the running environment is the development environment, the development data source is used for testing. When the running 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 an API is in Basic mode and the running environment is the development environment, the production data source is used for testing.

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

Step 1: Test the API

1. In the top menu bar of the Dataphin homepage, choose Service > API Development.

2. In the upper-left corner, select a service project. In the navigation pane on the left, choose API Service > API 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 under the Actions column of the target API to open the Version Management panel, and then click Test in the Actions column of the target API to go to the API test page.

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

   1. Configure the parameters in the Business Request Parameters area.

      • If the operation type is GET or LIST, the Test Input Value is a field value from your business data. The list parameters are the request parameters you configured when creating the API.

      • If the operation type is Create, Update, or Delete, the list fields are the request parameters you configured when creating the API. You can add, copy, or delete parameters as follows.

        • Add Parameter Item: Click the Add Parameter Item button. Enter a parameter value according to the prompt after the field. You can add up to the maximum number of input entries for the API.

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

          • Separator: A character used to separate fields. You can use a comma (,), semicolon (;), VERTICAL LINE (|), tab character (\t), or a custom character (you can enter multiple characters) to separate multiple parameters.

          • Text qualifier: A character used to define text fields. You can select None, double quotation marks (""), or single quotation marks ('').

        • Full-screen Input: Click Full-screen Input. Then, click Add 1 row, Add 5 rows, or Add 10 rows at the bottom 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 a new row with the cloned values at the end.

        • Delete: Click the Delete icon in the Actions column or select parameters in the list. Then, click the Batch Delete button at the bottom to delete the entire row of parameters.

   2. Configure the parameters in the Common Request Parameters area.

      • If the API is a direct-connection data source API (query type) or a service unit API, the system displays different parameters (PageStart, PageSize, and OrderByList) based on the API's 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), service unit API, or composite API, and 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 testing an API, the input parameter length cannot exceed 1,000 characters. If you call the API directly, there is no character length limit.

        Parameter	Description	Debugging input values
        AccountType	When authenticating in proxy mode, you must specify the account type of the proxy user. ACCOUNT_NAME: The username in Dataphin. USER_ID: The unique ID within Dataphin. SOURCE_USER_ID: The source system account ID. Note This parameter is required only when DelegationUid is set. If this parameter is not specified, the default type is USER_ID.	Select the account type for the specified proxy user. You can choose ACCOUNT_NAME, USER_ID, or SOURCE_USER_ID.
        DelegationUid	The user on whose behalf the access is being proxied. You must pass the corresponding account ID based on the selected AccountType. Setting this parameter enables authentication in proxy mode.	Only the current tenant account can be used as the DelegationUid.
        ApiVersion	Specifies the API version to call. The latest version is used by default.	The test input value is obtained by switching the version in the upper-right corner of the page. Note When the running environment is the development environment, the apiVersion parameter is supported. You can only select a submitted API to call.
        PageStart	Defines the starting entry number for the returned data.	Set to a positive integer, such as 2.
        PageSize	Defines how many data entries to return per page.	Set to a positive integer, such as 56.
        OrderByList	Defines the sorting method for multiple return parameters. If not specified, the default is ascending order.	The test input value must be obtained from the Business Request Parameters list.
        ReturnTotalNum	Defines whether to return the total number of rows in the result. When ReturnTotalNum=true, the total number of rows is returned, but this may affect performance.	This parameter is displayed when the API operation type is List and paged query is enabled. Set to a positive integer, such as 1000.

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

   4. In the Optional Return Parameters area, select the return parameters. The list of return parameters corresponds to 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 API's protocol and the number of returned entries.

      Parameter	Description
      Protocol	If you selected both HTTP and HTTPS as protocols when creating the API, you can choose the protocol when testing the API.
      Return Count	Defines the number of data entries to return when testing the API: If the request method is LIST, you can select the Return Count. A maximum of 10,000 data entries can be returned. If the request method is GET, you cannot modify the Return Count.

4. After you complete the configuration, click Debug or Test next to the Return Count field to test the API call with the provided input values and verify that the API configuration meets your business requirements.

   • When testing the API, you can click View Script to view the SQL script. This helps you compare whether the query result matches the expected script output.

     Note

     • You cannot view the script for registered APIs or model APIs because they do not have SQL scripts.

     • When calling a composite API, if the referenced API has row-level permission controls, the AccountType and DelegationUid parameters must be passed to the referenced API.

     • To call a composite API in proxy mode, you only need to request proxy permissions for the composite API.

   • If the API call mode is asynchronous mode, the query result is displayed in the test result area after the test. You can view the running result, log, code, and other information in the test result. For more information about the asynchronous query flow, see Asynchronous invocation process.

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

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

     • View Log: Click the Get Query Status tab to view the execution log of the API call. To cancel the API test, click Cancel Query to cancel the query request.

     • View query result: Click the Get Query Result tab to view the final query result returned in the body of the API call.

5. In the Return Result or Test Result area, view the test result. The system caches the last 10 test and debugging data entries based on the API_ID, allowing you to compare results.

   If the test fails, see Appendix: Error codes and solutions.

6. While testing the API, you can also edit the API, run another test, or grant API permissions.

   • Edit API: Click the Edit API button at the bottom to modify the configuration of the current API. For more information, see Edit an API.

   • Test: Click the Test button at the bottom. The system calls the API with the test input values to verify that the API configuration meets your business requirements.

   • Grant API Permissions: Click the Grant API Permissions button at the bottom to grant permissions for the API to an application. For more information, see DataService Studio permission management.

Step 2: Publish the API

After publishing, business application users can find the API on the DataService Studio Overview page and request permission to call it.

Appendix: Error codes and solutions