All Products
Search
Document Center

DataWorks:Register an API

Last Updated:Feb 04, 2024

You can register existing APIs in DataService Studio to publish and manage the APIs in a centralized manner. For example, you can view the call information and call logs of APIs and manage API tags and versions. This topic describes how to register and configure an existing API.

Register an API

If no APIs are available, you must create an API. For more information about how to create an API, see Create an API by using the codeless UI.

  1. In the Service Development pane of the DataService Studio page, move the pointer over the 新建 icon and choose Create API > Register API.

    You can also expand the desired business process, right-click API, and then choose Create API > Register API.

  2. In the Register API dialog box, configure the parameters. The following table describes the parameters.

    注册API

    Parameter

    Description

    API Name

    The name of the API. The name must be 4 to 50 characters in length and can contain letters, digits, and underscores (_). The name must start with a letter.

    API Path

    The path in which the API is stored. Example: /user.

    Note

    The path can be up to 200 characters in length and can contain letters, digits, forward slashes (/), underscores (_), and hyphens (-). The path must start with a forward slash (/).

    Protocol

    The protocol that is used by the API. Valid values: HTTP and HTTPS.

    If you want to call an API by using HTTPS, you must bind an independent domain name to the API group to which the API belongs in the API Gateway console after you publish the API to API Gateway. You must also upload an SSL certificate in the API Gateway console. For more information, see Enable HTTPS for an API operation.

    Request Method

    The request method that is used by the API. Valid values: GET, POST, PUT, and DELETE.

    Response Type

    The format of the data that is returned by the API. Valid values: JSON and XML.

    Visible Scope

    The visible scope of the API. Valid values:

    • Workspace: The API is visible to all members in the current workspace.

    • Private: The API is visible only to its owner, and permissions on the API cannot be granted to other members.

      Note

      If you set this parameter to Private, other members in the current workspace cannot view the API in the API list.

    Label

    The tags that you want to add to the API. Select tags from the Label drop-down list.

    Note

    A tag can be up to 20 characters in length and can contain letters, digits, and underscores (_). You can add up to five tags to an API.

    Description

    The description of the API. The description can be up to 2,000 characters in length.

    Destination Folder

    The folder in which you want to store the API.

  3. Click OK.

Configure the API

  1. Double-click the name of the registered API. On the configuration tab of the API, configure the parameters in the Define Backend Service section. The following table describes the parameters.

    后端服务定义

    Parameter

    Description

    Host

    The host of the registered API. The hostname must start with http:// or https://, and cannot contain the path.

    Path

    The path of the registered API. The path can contain parameters that are enclosed in brackets []. Example: /user/[userid].

    In the next step, the parameters that are defined in the Path parameter are automatically added to the request parameter list.

    Back-end Service Timeout

    The timeout period of the backend service.

  2. In the Define Request Parameters section, configure the parameters based on your business requirements. The following table describes the parameters.

    请求参数定义

    Parameter or section

    Description

    Request Parameters

    In this section, you can click Add Parameter to add a request parameter for the API.

    For each request parameter, you can set the Parameter Position field to QUERY, HEAD, or BODY. The valid values of the Parameter Position field vary based on the request method that is used by the API. Select a value from the valid values that are displayed.

    Constant Parameters

    Constant parameters have fixed values and are invisible to API callers. You do not need to specify constant parameters during an API call. However, the backend service receives the defined constant parameters and their values in each API call.

    If you need to fix the value of a parameter or hide the parameter for API callers, you can use constant parameters.

    Request Body Description

    This parameter is displayed only if you set the Request Method parameter to POST or PUT.

    In the Request Body Description parameter, you can enter the body description in the JSON or XML format. This way, you can provide an example of the request body for API callers to determine the format of the request body.

  3. In the Define Response Content section, configure the Correct Response Example and Error Response Example parameters. The response examples are only for reference. API callers can write code for parsing the responses of the API based on the examples.

  4. In the Define Error Codes section, configure the Error Code, Error Message, and Solution parameters to define an error code. The information helps API callers identify the cause of the error.

  5. Click the 保存 icon in the top toolbar.

    After the API is configured, you can test it. For more information, see Test an API.

    After the test succeeds, click Submit in the upper-right corner.

    In the right-side navigation pane of the API configuration tab, click Version. Find the API version that you want to publish and click Application for publication in the Actions column to go to the application page. Use the default application type Publish data service API and enter the reason for the application in the Reason for application field. Then, click Apply for permission to submit the application.

    Note

    If you defined an approval policy in DataWorks Approval Center, the API must be approved before the API can be published. For more information, see Overview.

    After the API is published, the configuration of the resource group for DataService Studio takes effect when the API is called.

    On the Service Development tab, you can find the registered API in the left-side navigation pane and manage the API. For example, you can clone or delete the API. On the Service Management tab, you can find the published API and view the details of the published API. For more information, see View, delete, move, and clone an API, perform batch operations on multiple APIs, and use the code search feature to search for APIs.