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 your administrator has enabled the use of both local and cloud-managed connectors, you must
also have access to the App Connect on IBM® Cloud instance that hosts the
cloud-managed connectors.
- If you know which applications or imported APIs you want to interact with, open the App Connect Designer catalog and create accounts for the local or cloud-managed
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, open the
App Connect Designer dashboard (if not currently on display) by clicking the
Dashboard icon .
- Click .
The API editor opens with a Define tab and a Manage
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 Manage tab to obtain an
auto-generated base URL for the API, and a user name and password that can be specified when
invoking the 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 for local or
cloud-managed connectors, 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.
- To manually input text, mappings, and JSONata expressions into the fields, or to define your own
custom values, see Configuring
actions.
- To auto populate the fields for the action with suggested smart mappings, use the Mapping Assist
capability as described in Mapping your data by applying smart suggestions. (To apply smart mappings,
Mapping Assist must be enabled in your App Connect Designer instance.)
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 Asset
Repository 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.
After you've sufficiently tested the flow, you can choose to export
it as a broker archive (BAR) file that packages the integration. You can then upload this BAR file
to an App Connect Dashboard instance for deployment to an integration server
that runs the integration in production systems. For more information, see Deploying IBM App Connect Designer flows and APIs to integration servers.