Test and publish an API

Prerequisites

An API is created. For more information, see Create an API.

Direct connection mode and proxy mode

DataService supports direct connection mode and proxy mode for API calls. If an API has row-level permissions, the authentication method depends on the call mode.

• Direct connection mode: Request row-level permissions for the DataService Studio application. The application handles authentication.

• Proxy mode: Request row-level permissions for the DataService Studio application, then request proxy permissions. The application calls the API on behalf of the user.

API test page controls

• View domain name: Displays the internal testing domain name. For client call domain names, see View domain names.

• Switch APIs: Switch between submitted and published APIs in the upper-left corner. Search by API name or ID across all accessible APIs in the current service project. The system recommends the last nine APIs you accessed (viewed, edited, tested, or created) in the current project.

• Switch API running environments: Switch between development and production environments. Development uses the development data source; production uses the production data source. Unpublished APIs cannot be tested in production.

  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: Switch API versions in the upper-right corner. The development environment shows submitted versions; the production environment shows published versions.

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.

   • On the API page, click More > Version Management under the Actions column of the target API. In the Version Management panel, click Test in the Actions column.

3. On the API Test page, enter parameter values and verify that the returned results meet 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 listed fields are the request parameters configured when creating the API. You can add, copy, or delete parameters:

        • Add Parameter Item: Click Add Parameter Item and enter parameter values. 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 values. Separate parameter groups with new lines. Configure separators and text qualifiers as needed.

          • Separator: Separates fields. Options: comma (,), semicolon (;), vertical line (|), tab (\t), or a custom character.

          • Text qualifier: Defines text field boundaries. Options: 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 to add rows.

        • Copy: Click the Copy icon in the Actions column to clone the current row and append it to the list.

        • Delete: Click the Delete icon in the Actions column, or select parameters and click Batch Delete to remove rows.

   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, input parameter length cannot exceed 1,000 characters. No limit applies when calling the API directly.

        Parameter	Description	Debugging input values
        AccountType	When authenticating in proxy mode, 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 proxied. Pass the corresponding account ID based on the selected AccountType. Setting this parameter enables proxy mode authentication.	Only the current tenant account can be used as the DelegationUid.
        ApiVersion	Specifies the API version to call. Uses the latest version 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 return parameters. Defaults to ascending order.	The test input value must be obtained from the Business Request Parameters list.
        ReturnTotalNum	Defines whether to return the total row count. When ReturnTotalNum=true, the total row count is returned, but performance may be affected.	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 with row-level permissions enabled, the Row-level Permissions area displays the name and description of row-level permissions for the current API version and environment.

   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 both HTTP and HTTPS were selected when creating the API, choose the protocol for testing.
      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. Click Debug or Test next to the Return Count field to verify the API configuration meets your business requirements.

   • Click View Script to view the SQL script and compare query results against expected output.

     Note

     • Script viewing is unavailable for registered APIs and model APIs.

     • When calling a composite API, pass the AccountType and DelegationUid parameters to any referenced API with row-level permission controls.

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

   • If the API call mode is asynchronous, the query result appears in the test result area. View the running result, log, and code in the test result. For the asynchronous query flow, see Asynchronous invocation process.

     • View request result: Click Call API > Return Result to view the response body.

     • Script Code: Click Call API > Script Code to view the SQL statement.

     • View Log: Click Get Query Status to view the execution log. Click Cancel Query to cancel the request.

     • View query result: Click Get Query Result to view the final response body.

5. In the Return Result or Test Result area, view the test result. The system caches the last 10 test results per API for comparison.

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

6. While testing, you can also edit the API, retest, or grant API permissions.

   • Edit API: Click Edit API at the bottom to modify the API configuration. Edit an API.

   • Test: Click Test at the bottom to call the API with the test input values.

   • Grant API Permissions: Click Grant API Permissions at the bottom to grant API permissions to an application. DataService Studio permission management.

Step 2: Publish the API

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

Appendix: Error codes and solutions