You can register existing APIs in DataService Studio to centrally manage, publish, and integrate the APIs. This topic describes how to register and configure an existing API.

Register an API

If you have no APIs, you must create an API. For more information, see Create an API by using the codeless UI.

  1. In the Service Development pane, move the pointer over the Create icon and choose New API > Register API.
    You can also click a business process, right-click API, and then choose New API > Register API.
  2. In the Register API dialog box, set the parameters as required.
    Register an API
    ParameterDescription
    API NameThe 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 PathThe path of 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 (/).
    ProtocolThe protocol used by the API. Valid values: HTTP and HTTPS.

    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 an SSL certificate in the API Gateway console. For more information, see Enable HTTPS for an API operation.

    Request MethodThe request method used by the API. Valid values: GET, POST, PUT, and DELETE.
    Response Content TypeThe format of the data returned by the API. Valid values: JSON and XML.
    Visible RangeThe 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 members.
      Note If you set this parameter to Private, other members in the workspace cannot view the API in the API list.
    LabelThe tags to be added 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.
    DescriptionThe description of the API. The description can be up to 2,000 characters in length.
    Destination FolderThe folder that stores the API.
  3. Click OK.

Configure the API

  1. Double-click the registered API. On the configuration tab of the API, set the parameters as required in the Define Backend Service section.
    Define Backend Service
    ParameterDescription
    HostThe host of the registered API. The hostname must start with http:// or https://, and cannot contain the path.
    PathThe path of the registered API. The path can contain parameters that are enclosed in brackets []. Example: /user/[userid].

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

    Back-end Service TimeoutThe timeout period of the backend service.
  2. In the Define Request Parameters section, set the parameters as required.
    Define Request Parameters
    Parameter or sectionDescription
    Request ParametersYou 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 one from the valid values that are displayed.

    Constant ParametersConstant parameters have fixed values and are invisible 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.

    The constant parameters are applicable when you need to fix the value of a parameter or hide the parameter from API callers.

    Request Body DescriptionThis 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, set the Correct Response Example and Error Response Example parameters. These examples are references for API callers to write the code for parsing the results of the API.
  4. In the Define Error Codes section, set the Error Code, Error Message, and Solution parameters to define an error code. The information helps API callers diagnose the causes of the error.
  5. Click the Save icon icon in the toolbar.
    After the API is configured, you can test it. For more information, see Test an API.

    After the test succeeds, click Submission 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. You can use the default application type and enter the reason for the application. Then, submit the application.
    Note If you have defined an approval policy in DataWorks Approval Center, the API must be approved through the approval process 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 in the API list and view the details of the published API. For more information, see View, delete, move, and clone an API.