This topic describes how to register and configure an existing API.

Register an API

  1. Go to the DataService Studio page.
    1. Log on to the DataWorks console.
    2. In the left-side navigation pane, click Workspaces.
    3. In the top navigation bar, select the region where the target workspace resides. Find the target workspace and click DataService Studio in the Actions column.
  2. On the Service Development tab, move the pointer over Create icon and choose API > Register API.
    You can also click the target business process, right-click API, and then choose New > Register API.
  3. In the Register API dialog box, set the parameters as required.
    Register API dialog box
    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 (_). It must start with a letter.
    API Path The path for storing the API, such as /user.
    Note The path can be up to 200 characters in length and can contain letters, digits, underscores (_), and hyphens (-). It must start with a forward slash (/).
    Call Mode The mode for calling the API. Valid values: Synchronous Call and Asynchronous Call.
    • If you set this parameter to Synchronous Mode, the API returns results immediately after it is called. The synchronous mode is most commonly used.
    • If you set this parameter to Asynchronous Mode, the API returns the RequestID parameter immediately after it is called. The API caller can then obtain the call result from a message queue based on the request ID.
    Protocol The protocol used by the API. Valid values: HTTP, HTTPS, and HSF.

    If you need to call the API by using HTTPS, you must bind an independent domain name to the API in the API Gateway console after the API is published to API Gateway. In addition, you must upload a Secure Sockets Layer (SSL) certificate in the API Gateway console. For more information, see Enable HTTPS for an API operation.

    Request Method The request method used by the API. Valid values: GET, POST, PUT, and DELETE.
    Response Content Type The format of the data returned by the API. Valid values: JSON and XML.
    Visible Range The range of users to whom the API is visible. Valid values:
    • Work Space: 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 users.
      Note If you set this parameter to Private, other members in the workspace cannot view the API in the API list.
    Label The tags to be attached to the API.
    Note A tag can be up to 20 characters in length and can contain letters, digits, and underscores (_). You can set at most five tags for an API.
    Description The description of the API, which can be up to 2,000 characters in length.
    Target Folder The folder for storing the API.
  4. Click OK.

Configure the API

  1. Double-click the registered API. On the tab that appears, set the parameters in the Define the back-end Service section.
    Define the back-end Service section
    Parameter Description
    Back-end Service Host The host of the registered API. The host must start with http:// or https://, and cannot contain the path.
    Back-end Service Path The path of the registered API. The path can contain parameters that are placed in brackets [], for example, /user/[userid].

    In the next step, parameters defined in Back-end Service Path 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, set the parameters as required.
    Define Request Parameters section
    Parameter Description
    Request Parameters You can click Add Parameters 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 values of the Parameter Position field vary with the request method used by the API. Select one from the available options.

    Constant Parameters Constant parameters have fixed values and are hidden to API callers. The constant parameters do not need to be specified during an API call. However, the backend service receives the defined constant parameters and their values in each API call.

    Constant parameters are applicable if you need to fix the value of a parameter or hide the parameter to API callers.

    Request Body Description This field appears only when you set the Request Method parameter to POST or PUT.

    In the Request Body Description field, you can enter the body description in the JSON or XML format. In 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, set the Correct Response Example and Error Response Example parameters. These examples are reference for API callers to write the code for parsing the results of the API.
  4. In the Error Codes section, click New error code and set the Error Code, Error Message, and Solution parameters. The information helps API callers locate the error causes.
  5. Click Save icon in the toolbar.
    After the API is configured, you can test it. For more information, see Test an API.

    After the API is tested, close the Test APIs dialog box, and click Publish in the upper-right corner of the configuration tab.

    On the Service Development tab, you can double-click the published API to view the details of the API and clone or delete the API.