Developing an API Workflow

API orchestration allows you to reorganize and reconstruct APIs in a visualized manner based on specific service logic and processes without compiling code. In this way, you can perform secondary development easily without affecting native APIs. API orchestration provides you with drag-and-drop and visualized API workflow orchestration capabilities. You can combine multiple APIs into a workflow in serial or parallel mode based on the service logic, invoke the API workflow through the entry API, and obtain the required data.

API orchestration provides more intuitive and efficient design and optimization of business processes, and more convenient secondary development. You can use API orchestration in the following scenarios to simplify development:

Map or convert the format of a returned message through API orchestration.
A data request depends on multiple data APIs: API orchestration reduces the number of API calls, cuts down integration costs, and improves efficiency.

Constraints

API orchestration is available only for DataArts DataService Exclusive clusters of version 3.0.6 or later.
Before publishing an API workflow, ensure that all common APIs in the workflow have been published.

Introduction to Operators and Workflows

On the API workflow orchestration page, you can drag various types of operators to the canvas, connect them to orchestrate a workflow based on specific service logic and processes, configure the operators, and save, debug, and publish the workflow.

API orchestration supports five types of drag-and-drop operators: Entry API, Common API, Conditional Branch, Parallel Processing, and Output Processing. A workflow starts with an Entry API operator and ends with an Output Processing operator, with any combination of Common API, Conditional Branch, and Parallel Processing operators in the middle. A workflow must meet the following requirements:

It starts with and contains only one Entry API operator which can have only one downstream branch.
It contains at least one Common API operator at the middle layer. The Common API operator has upstream and downstream operators, but can have only one downstream branch.
Conditional Branch operators are optional and located at the middle layer. They must have at least two branches and can have a maximum of 20 branches. If multiple branches meet a condition, only the first branch is executed.
The Output Processing operator cannot be the direct downstream operator of a Conditional Branch operator. Instead, Conditional Branch operators obtain the request parameters or result sets of their upstream operators for condition judgment.
Parallel Processing operators are optional and located at the middle layer. They must have at least two branches and can have a maximum of 20 branches. Failure policies must be configured for Parallel Processing operators.
The Output Processing operator cannot be the direct downstream operator of a Parallel Processing operator. The logic of multiple branches can be executed at the same time without any impact on each other.
An API workflow ends with and can have only one Output Processing operator. The direct upstream operator of the Output Processing operator must be a Common API operator, and at least one result mapping must be configured.
An API workflow cannot have a ring structure or isolated operators. A maximum of 20 layers are supported.

Figure 1 API workflow orchestration page

**Table 1** API workflow operators
Navigation Path	Operator	Mandatory	Description
Triggers	Entry API	Yes	An API workflow starts with the Entry API operator. After the API workflow is published, it can be invoked through the Entry API operator. In the Entry API operator, you need to define the API workflow name, URL, parameter protocol, request method, reviewer, security authentication, and request parameters. For details about how to configure an Entry API operator, see Entry API Operator.
API Catalogs	Common API	Yes	Common API operators are used to perform data query operations. Common APIs are APIs you have created. During API orchestration, you can drag a Common API operator from the API catalog, use the operator to obtain data, and transfer request parameters or result sets as variables. For details about Common API operators, see Generating an API Using Configuration or Generating an API Using a Script or MyBatis.
Logic Controllers	Conditional Branch	No	The Conditional Branch operator obtains the request parameters or result sets of its upstream operator for condition judgment and determines the next branch to be executed based on the defined expression. If the conditions of multiple branches are met, only the first branch is executed. For details about how to configure Conditional Branch operators and expressions, see Conditional Branch Operator.
	Parallel Processing	No	The Parallel Processing operator can execute multiple branches at the same time. The branches do not affect each other. For details about how to configure Parallel Processing operators, see Parallel Processing Operator.
	Output Processing	Yes	The Output Processing operator maps the error codes and result sets, and converts the format of an API workflow to determine the format of the returned data. For details about how to configure Output Processing operators, see Output Processing Operator.

Developing an API Workflow 1: Mapping or Converting the Format of a Returned Message

To convert the result returned by an API from JSON data into an Excel file, perform the following operations:

On the DataArts Studio console, locate an instance and click Access. On the displayed page, locate a workspace and click DataArts DataService.
Figure 2 DataArts DataService

In the left navigation pane, choose an edition, for example, Exclusive Edition. The Overview page is displayed.
Choose API Development > API Orchestration and click Create.
Figure 3 API orchestration page
Drag the Entry API operator to the canvas, click the operator, and configure its parameters.
Figure 4 Configuring the Entry API operator
Drag the target Common API operator to the canvas and mount it to the Entry API operator. Click the Common API operator and copy its code, for example, NormalApi_5274d.
Figure 5 Copying code
Drag the Output Processing operator to the canvas and mount it to the Common API operator. Click the Output Processing operator configure its parameters.
- Add a result set mapping. Enter the result of the Common API operator for the mapping expression, for example, ${NormalApi_5274d|payload} and enter the result set name, for example, Sales records.
- Select EXCEL for Return Format.
Figure 6 Configuring the Output Processing operator
Save the API workflow, debug it, and publish it to the cluster. After that, the Entry API operator of the API workflow can be invoked to save the data obtained by the common API to an Excel file.

Developing an API Workflow 2: A Data Request Depends on Multiple Data APIs

A department of an e-commerce company wants to provide supplier information and sales rating data for users in area1 and provide retailer information for users in other areas.

The following APIs are available: AreaInformation, SupplierInformation, SalesRating, and RetailerInformation. You can create an API workflow that meets the department's demands by performing the following steps:

On the DataArts Studio console, locate an instance and click Access. On the displayed page, locate a workspace and click DataArts DataService.
Figure 7 DataArts DataService

In the left navigation pane, choose an edition, for example, Exclusive Edition. The Overview page is displayed.
Choose API Development > API Orchestration and click Create.
Figure 8 API orchestration page
Drag the Entry API operator to the canvas, click the operator, and configure its parameters.
Figure 9 Configuring the Entry API operator
Drag the AreaInformation API operator in the API catalogs to the canvas and mount it to the Entry API operator. Click the AreaInformation API operator and copy its code, for example, NormalApi_ff8bd.
Figure 10 Copying the code of the AreaInformation operator
Drag the Conditional Branch operator to the canvas, mount it to the AreaInformation operator, and mount the Parallel Processing operator and RetailerInformation operator to the Conditional Branch. The code of the RetailerInformation operator is NormalApi_de62d.
Click the Conditional Branch operator on the canvas and configure its parameters.
- For the Parallel Processing operator, set Condition Type to Meets the current condition and Expression to ${NormalApi_ff8bd|payload.data[0].area}. The expression is used to obtain the field value in the first row and the area column in the result set of the AreaInformation API. If the obtained field value is area1, the Parallel Processing operator is executed.
- For the RetailerInformation operator, set Condition Type to Does not meet other conditions. If the conditions of the Parallel Processing operator are not met, the RetailerInformation operator is executed.
Figure 11 Configuring the Conditional Branch operator
Drag the SupplierInformation API and SalesRating API operators in the API catalogs to the canvas, and mount them to the Parallel Processing operator. The code of the SupplierInformation operator is NormalApi_3ad5c and that of the SalesRating operator is NormalApi_01e7e.
Click the Parallel Processing operator and set Policy Upon Branch Failure and Timeout Duration for the SupplierInformation and SalesRating operators. (retain their default values.) When the Parallel Processing operator is executed, the SupplierInformation and SalesRating operators are both scheduled.
Figure 12 Configuring the Parallel Processing operator
Drag the Output Processing operator to the canvas and mount it to the three Common API operators. Click the Output Processing operator and add result set mappings.
Add three mappings to output the results of the three Common API operators. Set the expressions of the mappings to the results of the corresponding Common API operators, for example, ${NormalApi_3ad5c|payload}, ${NormalApi_01e7e|payload}, and ${NormalApi_de62d|payload}, and set the result set names.
Figure 13 Configuring the Output Processing operator
Save the API workflow, debug it, and publish it to the cluster. After that, the Entry API operator of the API workflow can be invoked to return different information for users in different areas.

Related Operations

Editing an API workflow: On the API workflow list page, locate a workflow, and click Edit in the Operation column. On the displayed page, orchestrate the workflow again or modify it.
Viewing API workflow authorization: On the API workflow list page, locate a workflow and click View in the Operation column to access the API information page, where you can authorize the workflow.
If the app authentication mode is used for the Entry API, you must create an app and authorize the app to use the API before invoking the API workflow. The workflow authorization method is basically the same as the API authorization method. For details, see authorizing an app to use an API.
Debugging an API workflow: On the API workflow list page, locate a workflow, click More in the Operation column, and select Debug.
Add request parameters and click Test. The response of the API call is displayed in the result output area on the right. The workflow debugging process is basically the same as the API debugging process. For details, see Debugging an API.
Publishing an API workflow: On the API workflow list page, locate a workflow, click More in the Operation column, and select Publish.
An API workflow is available only after it is published. The workflow publishing process is basically the same as the API publishing process. For details, see Publishing an API.
Unpublishing/Deleting an API workflow: On the API workflow list page, locate a workflow, click More in the Operation column, and select Unpublish to unpublish the workflow. Select a workflow and click Delete above the workflow list to delete the workflow.
If you want to stop a published API workflow from providing services, you can unpublish it. The authorization information will not be retained after the API workflow is unpublished. If you no longer need the suspended API, you can delete it. The deletion cannot be undone. The process of unpublishing/deleting an API workflow is basically the same as that of unpublishing/deleting an API. For details, see Unpublishing/Deleting APIs.
Suspending/Restoring an API workflow: On the API workflow list page, locate a workflow, click More in the Operation column, and select Suspend or Restore.
To edit or debug a published API workflow, you must suspend the API workflow first. After the API workflow is suspended, its authorization information is retained. You can still edit and debug the API workflow. You can resume the API workflow so that it can continue to provide services. The process of suspending/resuming an API workflow is basically the same as that of suspending/resuming an API. For details, see Suspending/Restoring an API.
Displaying an API workflow: On the API workflow list page, locate a workflow, click More in the Operation column, and select Display.
Then you can set the visibility scope of the API workflow in the service catalog. The process of setting the visibility scope of an API workflow is basically the same as that of setting the visibility scope of an API. For details, see Displaying an API.
Copying an API workflow: On the API workflow list page, locate a workflow, click More above the list, and select Copy.
By copying an API workflow, you can obtain an API workflow with the same configuration as the source API workflow. The processing of copying an API workflow is basically the same as that of copying an API. For details, see Copying an API.
Synchronizing an API workflow to Data Map: On the API workflow list page, locate a workflow, click More above the list, and select Synchronize to Data Map.
This allows you to view API workflows in Data Map. The processing of synchronizing an API workflow to Data Map is basically the same as that of synchronizing an API to Data Map. For details, see Synchronizing APIs to Data Map.