App Connect Enterprise certified container only: Creating flows for an API from scratch

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.

To create an API flow, complete the following steps:

1. From the App Connect Designer UI, click the Dashboard icon to open the App Connect Designer dashboard (if not currently on display).
2. Click Create > Flows for an API (or New > Flows for an API 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.

   
3. 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.

4. 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.
   1. In the Model name field, enter a name for your model.
   2. Click Create model.
      The model panel is displayed with two tabs: Properties and Operations.
5. From the Properties tab, define the structure of the model.
   1. 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.

      
   2. 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.

      
6. 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.

   
7. 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.

     
8. Configure a flow that implements the operation:
   1. 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.

      
   2. 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.
   3. 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 Simplifying data mapping and data transformation with AI-powered 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.
   4. Optional: Add further applications or imported APIs if required.
   5. 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).
   6. Click the Response node in the flow to define the response that should be returned when the operation completes successfully.
   7. 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).
   8. 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.
   9. Click Done to return to your model.
9. Define further operations for the model and configure a flow that implements each operation, as described in steps 7 and 8.
   For example:

   
10. Define operations for any additional models and implement their flows.
11. Ensure that there are no validation errors in any of the implemented flows for the operations.
    For more information about validating the nodes in a flow and resolving errors, see Validating your flow is ready to run.
12. 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.

1. 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.
2. 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.