You can create flows for an API (alternatively referred to as an API
flow) in your App Connect Designer instance. The defined configuration
provides an API that exposes one or more operations that enable you to call out to an endpoint and
pass data between that endpoint and applications in the flow.
Before you begin
- To create flows for an API, you must have access to an App Connect Designer instance in your cluster.
- If you know which applications or imported APIs you want to interact with, open the App Connect Designer catalog and create accounts for the connectors that will run
API operations against the target applications or APIs. (It is also possible to create accounts
while creating a flow.) For more information, see Connecting to accounts.
About this task
When you create flows for an API, each individual flow is the implementation for an API operation
(such as 'GET order' or 'POST order') that is typically invoked from mobile and web applications.
The flow for each operation contains a request, actions for one or more applications or imported
APIs, optional toolbox nodes for specialized data processing, and a response for the API operation.
The request uses a model that you define to request the creation, retrieval, or replacement of data
objects in your applications. When the request is submitted, each target application or API performs
its action, and then the flow returns a response that either confirms that the actions were
successful, or returns the data that was requested.
Defining the API involves the following steps:
- Create one or more models that define the structure of the objects that you want to create or
retrieve. Up to 10 models are allowed.
- Choose the built-in create, retrieve, or replace or update operations to perform against each
model, or define your own custom operations.
- Configure a flow to implement each operation, adding actions for one or more target applications
or APIs. Optionally add toolbox utilities to the flow for specialized processing of the input or
output data from these applications.
Procedure
To create an API flow, complete the following steps:
- From the App Connect Designer UI, click the
Dashboard icon to open the App Connect Designer dashboard
(if not currently on display).
- Click (or in earlier versions).
The API editor opens with a Define tab and a Test
tab in view. You create models and operations for the API in the Define tab.
After you start the API, you can then use the Test tab to verify the behavior
of the flow by calling the endpoints for each of the implemented API operations.
- Enter a name that identifies the purpose of your flow.
As you progress with the flow, App Connect will automatically save
your changes. If you navigate away from the flow at any stage, the flow is saved as a draft flow
that you can complete at another time.
- Create a model that defines the structure of an object that you want to perform
operations on; for example, a customer object for which records can be created, retrieved, or
updated.
- In the Model name field, enter a name for your model.
- Click Create model.
The model panel is displayed
with two tabs: Properties and Operations.
- From the Properties tab, define the structure of the
model.
- To add the first property, type the name in the field provided and then select a data
type for that property.
By default, the first property that you add has the
ID option selected. A property that is set as the ID for the model indicates
that your flow must return this property when creating an object or that the property must be sent
in a request to update or retrieve an object by using its ID. You must set an ID against one
property in order to define operations for the model.
Tip: To add a property, you can
also click
Select properties from applications to choose properties from one
or more of the applications that you’re connected to. Ensure that the required account is selected.
Then select one or more properties and click
Add properties.
- Add other properties for the model by clicking Add a property +
.
Note:
- Each property name must be unique.
- Spaces are not allowed in the name, but you can use an underscore character (_) to separate
words.
- The name must contain only letters, numbers, or the underscore character.
- The name must begin with a letter or an underscore.
- The name must contain at least two characters.
- Create more models by clicking Create model and add properties for
each new model as described in step 5.
If you want to edit the name of a model, you can select Edit model
information from the menu. To delete a model, you can select Delete
model.
- To define how the API will interact with the model, click
Operations.
- To add one of the built-in operations, click within the Select an operation to
add drop-down list, and then choose a Create,
Retrieve, or Replace or create operation to perform
against the model.
- If you choose an operation that enables you to apply filters (for example,
Retrieve model_name with filter or Replace or
create model_name with filter), select the required filter
properties. For the Retrieve model_name with filter
operation, optionally enable and configure pagination settings for the results. (To apply filters,
at least two properties, including the
ID
property for the model, must be defined because the
ID
property cannot be selected as a filter.)
For more information about using these operations, see Introducing filter parameters for API flows in IBM App Connect
and Configuring pagination for the Retrieve with filter
operation
in API flows.
- To define your own operations, click within the Select an operation to
add drop-down list, and then choose Add a custom operation.
Restriction:
- The operation name cannot be any of these keywords:
create
,
updateOrCreate
, replaceOrCreate
, findOrCreate
,
buildNearFilter
, all
, destroyAll
,
count
, save
, update
, destroy
,
delete
, remove
, replaceById
,
updateAttributes
, patchAttributes
,
upsertWithWhere
, getChangeModel
, getIdName
,
getSourceId
, handleChangeError
, rectifyChange
,
replaceById
, replaceOrCreate
, replicate
,
updateAll
, upsert
, upsertWithWhere
,
destroy
, fillCustomChangeProperties
, getId
,
isNewRecord
, reload
, replaceAttributes
,
save
, setId
, updateAttribute
,
updateAttributes
.
- The query parameter cannot be the same as the model ID.
For more information about adding your own custom operations see, Creating custom HTTP operations on API flows.
- Configure a flow that implements the operation:
- Click Implement flow. For example:
You’ll see a basic flow structure in the flow editor, with a Request node,
a Response node, and a space to add one or more target applications, imported
APIs, or toolbox utilities. Notice the structure of the Request body example - it is constructed
from the properties in your model, with some sample data.
- To add an application or imported API to the flow, click (+)
and then select the application or API, and the required action. Also ensure that the correct
account, which App Connect will use to connect to the target
application or API, is selected. If there are no connected accounts, you can create one as described
in Connecting to accounts.
Note: If your
App Connect Designer instance has been configured to use a
switch server for callable flows, you can add Callable flow nodes that invoke running callable flows
in either
IBM App Connect Enterprise or
IBM Integration Bus on
premises. If this capability is enabled in your instance, a
Callable flows
icon
will be included in the navigation pane. You must also configure secure
connectivity as described in
Configuring connectivity between a calling flow and a callable flow.
- Populate the fields for the action with values that you want to pass to the target
application or API. You can specify static data in plain text, or specify dynamic data by adding
mappings from previous nodes in the flow. You can also apply functions (or JSONata expressions) to
transform your data, or use other built-in mechanisms to define custom values.
Tip: After you complete the fields for the action, you can use auto-generated or custom
sample data to
try out the action and verify its effect. The action will be performed
on the target application that you're connected to, so ensure that you use a non-production account
if you want to try out the action. For more information, see
Testing a non-running flow with sample data.
- Optional: Add further applications or imported APIs if required.
- Optional: Use one or more supported toolbox utilities to provide
specialized processing. For example, you can add an If node to provide
conditional processing, or a For each node to process retrieved items. For
more information, see Adding special processing to a flow (Toolbox utilities).
- Click the Response node in the flow to define the response that
should be returned when the operation completes successfully.
- In the Response header section, specify your preferred response
status code.
The following response codes are returned for the different operations:
- Create operations return a response code of 201 (record created).
- Retrieve operations return a response code of 200 (record retrieved).
- Replace or create operations return a response code of 200 (record replaced) or 201 (record
created).
- In the Response body section, define which fields should be
returned in the response body by using text, mappings from previous nodes in the flow, or JSONata
expressions.
Tip:
- When you’re creating an object, typically only the ID from the target application or API is
returned in the response message. If you’re retrieving an object, the response message will show you
all the fields that you’ve requested from the target application or API.
- After you have configured all of the flow's nodes, you can use auto-generated or custom sample
data to try out the flow before you start it in order to verify its behavior. The
configured actions in the flow will be performed on the target applications that you're connected
to, so ensure that you use non-production accounts if you want to try out the flow. For more
information, see Testing a non-running flow with sample data.
- Click Done to return to your model.
- Define further operations for the model and configure a flow that implements each
operation, as described in steps 7 and 8.
- Define operations for any additional models and implement their flows.
- Ensure that there are no validation errors in any of the implemented flows for the
operations.
- From the options menu on the Define tab, click Start
API to save and start your flow.
What to do next
Test the behavior of the API by using the built-in test facility to call the endpoints for each
of the implemented operations. You should see the response from the target applications within the
test facility, but can also check for the expected results in the UI of those applications. For more
information, see Testing a running API flow.
Click Dashboard to return to the dashboard. You should be able to see the
tile for your API flow.
From the flow menu, you can start, stop, export, or delete the API flow, and can choose to share it with other users as an asset if an Automation assets instance is available in your cluster. While the API flow
is running, you can also open it to view the configuration, but you’ll have to stop the flow if you
want to edit it.
To run the flow in a production system, deploy it as an
integration server or integration runtime in the
App Connect Dashboard, which provides a runtime
environment.
- After you successfully test the flow in your App Connect Designer
authoring environment, export the flow as a broker archive (BAR) file that packages the integration.
- Upload the BAR file to an App Connect Dashboard instance and then deploy
the file to an integration server or integration runtime to run the integration in the production
system.
For more information, see Deploying Designer and Toolkit integrations in the App Connect Dashboard.