Test and publish APIs

Prerequisites

Before you begin, ensure you have created an API. For more information, see Create an API.

API direct and proxy modes

The data service supports API calls in both direct mode and proxy mode. If an API is associated with row-level security, the call mode determines the authorization method.

• Direct mode: Authorization uses the application's own permissions. This requires you to grant row-level security to the data service application.

• Proxy mode: An application calls an API on behalf of a user. To enable this, you must grant row-level security to the application and also grant proxy permissions for the API to the application. The application then uses the user's permissions to authorize the API call.

Top actions for API testing

• 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 name.

• Switch API: In the upper-left corner of the page, switch between submitted and published APIs. You can use a fuzzy search by API name or ID to switch to any API you have permissions for in the current service project. The system recommends the last nine APIs that you have accessed (viewed, edited, tested, or created) in the current project.

• Switch API running environment: Switch the API running environment for testing. In the development environment, testing uses the development data source. In the production environment, testing uses the production data source. You cannot switch to the production environment for testing if the API is unpublished.

  Note

  If an API is in Basic mode and the running environment is the development environment, testing uses the production data source.

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

Step 1: Test an API

1. In the top navigation bar of the Dataphin homepage, choose Service > API development.

2. In the upper-left corner, select a service project. In the left-side navigation pane, choose API service > API to open the API page.

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

   • On the API page, in the Actions column for the target API, choose More > version management. In the version management panel, click Test for the desired API version to go to the API Test page.

3. On the API Test page, enter parameter values to verify that the returned parameters are correct.

   1. Configure the parameters in the business request parameter list section.

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

      • If the operation type is Create, Update, or Delete, the fields in the list are the request parameters that you configured when you created the API. You can use the following options to add, copy, or delete parameters:

        • Add Parameter Item: Click Add Parameter Item and enter parameter values based on the prompts next to each field. You can add records up to the API maximum input rows limit.

        • Batch Add: Click Batch Add. In the Batch Add Business Request Parameters dialog box, enter example parameter values. Separate each set of parameters with a line break. You can also specify a delimiter and a text qualifier for the parameters.

          • Delimiter: The character that separates fields. You can use a comma (,), semicolon (;), vertical bar (|), tab (\t), or a custom character or string to separate parameters.

          • Text qualifier: The character that encloses text fields. Valid values: None, double quotation marks (""), and single quotation marks ('').

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

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

        • Delete: Click the Delete icon in the Actions column, or select parameters from the list and click Batch Delete at the bottom to delete the selected rows.

   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 different parameters depending on the API's request method, such as PageStart, PageSize, and OrderByList.

        • If paged query is enabled, APIs with the LIST operation type display the PageStart, PageSize, and OrderByList parameters, while APIs with the GET operation type display only the OrderByList parameter.

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

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

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

        Note

        When you test an API, input parameters cannot exceed 1,000 characters. This limit does not apply when you call the API directly.

        Parameter	Description	Input value
        AccountType	When you use proxy mode for authentication, you must specify the account type of the delegated user. ACCOUNT_NAME: The Dataphin username. USER_ID: The unique ID within Dataphin. SOURCE_USER_ID: The ID of the source system account. Note This parameter is required only when the DelegationUid parameter is set. If this parameter is not specified, it defaults to USER_ID.	Select the account type of the delegated user. Valid values: ACCOUNT_NAME, USER_ID, and SOURCE_USER_ID.
        DelegationUid	Specifies the user on whose behalf the API is called. You must provide the corresponding account ID based on the selected AccountType. If this parameter is set, proxy mode is used for authentication.	The DelegationUid must be an account in the current tenant.
        ApiVersion	The API version to call. By default, the latest version is used.	To get the debugging input value, switch the version in the upper-right corner of the page. Note The apiVersion parameter is supported when the runtime environment is the development environment. In this environment, you can only call submitted APIs.
        PageStart	The starting row number for the returned data.	A positive integer, for example, 2.
        PageSize	The number of data records to return on each page.	A positive integer, for example, 56.
        useResultCache	Specifies whether to use the result cache. If enabled, query results for the same API with identical conditions and return fields are cached. If result cache is not enabled for the API, this parameter has no effect. This feature is suitable for queries on static data to reduce the frequency of identical SQL queries and improve query efficiency.	The default cache duration is 30 minutes. In versions V3.5.6 and later, you can set the cache duration for the target API on the API development > API service page. A boolean value, for example, true.
        keepColumnCase	Specifies whether the case of return parameters is preserved. If set to true, the case is preserved. If set to false, the field names returned by a direct-connection data source API are in uppercase by default.	A boolean value, for example, true.
        OrderBys	Defines the sort order for multiple return parameters. If not specified, the results are sorted in ascending order. Use commas (,) as delimiters.	Get the debugging input value from the business request parameter list.
        ReturnTotalNum	Setting ReturnTotalNum=true returns the total number of rows but may affect performance.	This parameter appears when the API operation type is LIST and paged query is enabled. A positive integer, for example, 1000.

   3. If the API is a direct-connection data source API (query type), a service unit API, or a composite API, and row-level permission is enabled, the Row-level Permission List section displays the enabled row-level permissions for the current API version and environment, including their names and descriptions.

   4. In the optional return parameter list section, select the return parameters. This list shows the available return parameters for 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 return parameters are selected by default and cannot be deselected.

   5. Configure the API protocol and the number of returned records.

      Parameter	Description
      Protocol	If you selected both HTTP and HTTPS as the protocol when you created the API, you can select a protocol when you debug the API.
      Number of returned records	The number of data records to return when testing the API: If the request method is LIST, you can select the number of returned records. The API can return a maximum of 10,000 data records. If the request method is GET, you cannot modify the number of returned records.

4. After you complete the configuration, click Debug or Test next to the number of returned records field. The system tests the API call with the specified input values to verify the API configuration.

   • During the API test, you can click view script to view the SQL script and check whether the query result matches the script's expected output.

     Note

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

     • When you call a composite API, if a referenced API is subject to row-level permission control, the AccountType and DelegationUid parameters must be passed to the referenced API.

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

   • If the API call uses asynchronous mode, the query result appears in the test result area after you test or debug the API. You can view the run result, logs, code, and other information in the test result area. For more information about the asynchronous query process, see Asynchronous call process.

     • View request result: Click the Call API tab, then click the Returned Results tab to view the response body.

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

     • View logs: Click the Get Query Status tab to view the execution logs for the API call. To cancel the API test or debugging, click Cancel Query.

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

5. In the Returned Results or Test Result area, view the test results. The system caches the 10 most recent test and debug records for each API_ID, allowing you to compare results.

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

6. While testing an API, you can also edit the API, rerun the test, and manage API authorization.

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

   • Test: Click the Test button at the bottom to rerun the test.

   • API authorization: Click the API authorization button at the bottom to authorize applications to call the API. For more information, see Data service permission management.

Step 2: Publish an API

After an API is published, application developers can find it on the Data Service overview page and request permission to call it.

Appendix: Error codes and solutions