IBM Cloud Pak for Integration only: Creating flows for an API from scratch

You can use the API editor to create an API flow and to define models and implement operations for your API. You can also optionally configure policy, gateway, and portal settings to control the API's behavior when it is published to API Connect after you start the flow.

To create an API flow, complete the following steps:

1. Applicable to Designer 12.0.12.4-r1 or later: Create the flow, create a model, and name the flow as follows.
   1. From your App Connect Designer instance, complete either of the following steps to create the flow:
      • From the Home page, click Create flows for an API.
      • From the navigation pane, click the Dashboard icon to open the App Connect Designer dashboard and then click Create > Flows for an API (or New > Flows for an API in earlier versions).
   2. From the Create flows for an API page, 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; for example, Customer.
      2. Click Create model.
         

      The API editor opens with a Designer tab, OpenAPI tab, and Gateway tab in view.

      • The Designer tab displays a model pane with two tabs: Properties and Operations. You can use the Properties tab to add properties for the model that you just created and to create more models if needed. You can use the Operations tab to create operations for the API.
      • The OpenAPI tab displays a representation of the API being authored in a format that conforms to the OpenAPI 3.0 specification.
      • The Gateway tab typically provides default settings that the gateway can use to invoke the published API in API Connect, and also enables you to optionally enforce additional API policies or configure gateway and portal settings for this API. If the conditions for unified authoring are not satisfied or if unified authoring is disabled, the Gateway tab only displays information about how to enable unified authoring.

      
   3. Enter a name that identifies the purpose of your flow.
      

      As you progress with the flow, App Connect automatically saves 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.

      To proceed, go to step 3.

2. Applicable to Designer 12.0.12.3-r1 or earlier: Create the flow, name the flow, and create a model as follows.
   1. From your App Connect Designer instance, complete either of the following steps to create the flow:
      • From the Home page, click Create flows for an API.
      • From the navigation pane, click the Dashboard icon to open the App Connect Designer dashboard and then click Create > Flows for an API (or New > Flows for an API in earlier versions).
      The API editor opens with a Designer tab, OpenAPI tab, and Gateway tab in view.

      • You create models and operations for the API in the Designer tab.
      • The OpenAPI tab displays a representation of the API being authored in a format that conforms to the OpenAPI 3.0 specification.
      • The Gateway tab typically provides default settings that the gateway can use to invoke the published API in API Connect, and also enables you to optionally enforce additional API policies or configure gateway and portal settings for this API.
        • If using App Connect Designer 12.0.5.0-r1-lts or later, this tab is always visible. If the conditions for unified authoring are not satisfied or if unified authoring is disabled, the Gateway tab only displays information about how to enable unified authoring.
        • If using an earlier App Connect Designer version, this tab is displayed only if you have access to an API Connect instance that is deployed to the Platform UI that also manages your App Connect Designer instance.

      
   2. Enter a name that identifies the purpose of your flow.
      

      As you progress with the flow, App Connect automatically saves 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.

   3. 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; for example, Customer.
      2. Click Create model.

      The model panel is displayed with two tabs: Properties and Operations.

      

      To proceed, go to step 3.

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

      
4. Create more models by clicking Create model and add properties for each new model as described in step 3.

   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.

   
5. To define how the API will interact with the model, click the Operations tab on the model pane.
   • 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.

     
6. 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.
7. Define further operations for the model and configure a flow that implements each operation, as described in steps 5 and 6.
   For example:

   
8. Define operations for any additional models and implement their flows.
9. 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.

   Before you start the flow, you can view the API definition for the API flow as described in step 10. You can also view and optionally configure gateway settings for invoking the API from API Connect as described in step 11.

10. Click the OpenAPI tab to view the API definition for the API flow within a form-based editor that is similar to the one used to edit APIs in API Connect. The details shown in this tab are read-only, but will be automatically updated to match any changes that you make to the models and operations in the API editor of the flow.
    On initial entry, the API definition is shown in the Form view within a number of sections. Some of these sections might not currently be applicable or display any details for the API. The General section is expanded by default, but you can expand any of the sections to view further details.

    • Components: This section displays reusable objects that relate to various aspects of the API definition:
      • Schemas: This section displays details about each model and its properties.
      • Responses: Not applicable
      • Parameters: Not applicable
      • Examples: Not applicable
      • Request Bodies: Not applicable
      • Headers: Not applicable
      • Security Schemes: This section displays details of the preconfigured API key security scheme that will be used to supply credentials (a client ID) when calling the API operations. The security scheme name is given as clientID with a type of apiKey, and an X-IBM-Client-Id parameter is used to pass the credentials in the request header of the API.
      • Links: Not applicable
      
    • General:
      • Info: This section displays the API summary including the flow name as the title, a generated name that is based on the flow name and which will be used to identify the API, and an assigned version (typically 0.0.1). The remaining fields are left blank.
      • Servers: This section displays the server definitions in the API, for connecting to a target server. The supplied server URL is interpreted as the basepath and will be used to construct the full URL endpoint for calling the API. The server URL starts with a forward slash (/), followed by the flow name with underscores (_) to replace spaces; for example, /Customer_API.
      • Security: This section displays the security requirements that will be enforced on the API. By default, a clientID security scheme of type apiKey is configured.
      • External Documentation: Not applicable
      • Tags: Not applicable
      
    • Paths: This section displays the Paths for each of the defined operations in the API flow. Each Path comprises an HTTP verb and a URL (relative) path, and defines how the API is exposed. You can click to expand each URL path in the left pane to explore further.
      • Servers: Not applicable
      • Parameters: Not applicable
      • Operations: Based on the operation type, you might see details such as tags (which correspond to the model name), path or query parameters, or response codes and descriptions.
      

    You can view the underlying OpenAPI YAML source for the API definition in the UI by clicking the Source icon . This view is also read-only, and the YAML source conforms to the OpenAPI 3.0 specification. (To switch back to the Form view, you can click the Form icon .)

    
11. Click the Gateway tab to view and optionally configure policies, and gateway and portal settings. Any settings that you configure here will affect the behavior of the API that is published in API Connect, but will have no effect on the running API within App Connect Designer.
    Tip: You can skip this step if you do not want to configure any policies, or gateway and portal settings.

    You can also skip this step if you are using App Connect Designer 12.0.5.0-r1-lts or later, and the conditions for unified authoring are not met, or unified authoring is disabled because you don't want the API to be published to API Connect. For information about disabling this feature, see Setting preferences for publishing the API to API Connect.

    • Policies: This view, which is presented on initial entry, displays the assembly editor and can be used to create assemblies to customize the API. An assembly is formed of elements (such as policies or logic constructs) that are applied to calls to, and responses from, operations in the API. The assembly editor includes a palette that lists the available elements, a slide-out property sheet that is used to configure an element, and a canvas that is used to arrange and visualize the assembly’s elements. For information about using this editor, see The assembly editor, API policies and logic constructs, and Handling errors in the assembly in the API Connect documentation.
      

      On initial entry into the Policies view, the canvas provides a single Invoke policy to execute the API. The gateway can use this policy to invoke the running API in App Connect Designer. You can click to open the property sheet for this policy, but do not need to edit any of the default settings, which also include a username and password for HTTP basic authentication. It's worth noting that the app-connect-designer-url variable in the URL field represents the URL of the current App Connect Designer instance, which the gateway will need to access. This URL is defined in the Gateway tab, under Gateway and portal settings > Properties.

      Note: Do not delete the default Invoke policy (titled Invoke flow) unless you can devise an alternative method to access the App Connect Designer endpoint URL defined by app-connect-designer-url, to call the API.
      

      You can add other policies or logical constructs from the palette to suit your requirements. For example, to restrict calls to the API, you can drag and drop a Rate limit policy into the required position in the assembly and then use the property sheet to define the maximum number of calls that are allowed in a specified time period. For more information, see Rate Limit in the API Connect documentation.

      Tip: If defined in the assembly, a rate limit will only affect calls at that point in the assembly. If the Plan allows a call to proceed, but a hard limit that is set on the assembly is exceeded, the call is aborted at the point in the process flow where the rate limit is set. Any actions that appear in the assembly's process flow before the rate limit policy are executed. Only the actions that appear in the flow after the rate limit policy are aborted.
      
    • Gateway and portal settings: This section provides general configuration settings for the API and allows you to update some of these settings. For more information, see Specifying gateway and portal settings in the API Connect documentation.
      
      Tip: The default app-connect-designer-url property (under Gateway and portal settings > Properties) defines the URL of your current App Connect Designer instance, which the gateway will use for access. Do not delete or edit this property.

      

To configure preference settings that determine where the API is published in API Connect when you start the flow, complete the following steps:

1. From the API editor where the flow’s Designer, OpenAPI, and Gateway tabs are located, click the Change API gateway settings icon . You can configure or update publishing preferences only if the flow is in a Stopped state.
   

   The API gateway settings panel opens.

   
2. To enable unified authoring, set Unified authoring to on.
   Note:

   • The Unified authoring switch is enabled by default so if you create an API flow and then start it without first setting publishing preferences for that flow, the last set of user preferences that were saved for a flow are used. If no preferences have been previously set in the Designer instance, the API is published to the Default Plan in an auto-generated Product within a Sandbox Catalog in any of your discovered API Connect instances. To control where your API is published, you must therefore ensure that you specify your preferred settings before you start the API.
   • If you do not want to publish the API to API Connect when you start the API flow, you must set Unified authoring to off and then click Save to confirm.
   • You cannot disable unified authoring or update other preferences while the flow is running after being started. You can view your selected preferences in read-only mode and will need to stop the flow if you want to update these preferences. When you stop the flow, the published API is deleted, and after you restart the flow, the API is republished in accordance with your updated preferences.
   • Your publishing preferences are preserved for the lifetime of the flow in Designer and are retained if you stop and restart the API, or if you disable and then re-enable unified authoring.
3. From the API management drop-down list, select the name of an API Connect instance (of type API management) that you are authorized to access, and to which you want to publish the API.
4. From the Provider organization drop-down list, select a provider organization in the selected API Connect instance.
5. Under Staging target and runtime settings, use the Edit links to define the staging target through which the Product (and API) can be published, and the Gateway services that should host the published API.

   Target catalog

   Specify the Catalog to which you want to publish the Product that contains the API. The selected Catalog is used as the scope for the other preference settings.

   • Use the default built-in Sandbox Catalog: Click this option to use the Sandbox Catalog.
   • Choose an existing catalog: Click this option to select a Catalog of your choice.

   Target space

   If the selected Catalog is partitioned into Spaces, specify the Space that you want to publish to.

   Note: If you opted to use the built-in Sandbox Catalog, the Target space option is not displayed because Spaces cannot be enabled for this Catalog. The Target space option is also not displayed if you chose an existing Catalog that is not partitioned into Spaces.

   
   

   Target gateway services

   Specify which Gateway services should provide the runtime capability for handling incoming traffic for the published Product and API. Typically, only discovered Gateway services with a datapower-api-gateway Gateway type are considered compatible.

   • Use all compatible gateway services: Click this option to use all discovered compatible Gateway services.
   • Select compatible gateway services: Click this option to select one or more compatible Gateway services of your choice. (Incompatible Gateway types will be disabled.)

   
6. Under API consumption settings, use the Edit links to define how to package the API for consumers and manage API usage.

   Target product

   Specify the Product that will contain the API.

   • Generate auto product: Click this option to use an automatically generated Product. The name of this product is shown as API title auto product in the API gateway settings panel, where API title represents the flow name. (This name will be different in your API Connect instance, as described later.)
   • Existing Product: Click this option to select an existing Product from the Catalog that you selected.

   Target product rate limit

   If you chose to publish to an auto-generated Product, configure a rate limit to control calls to the API. This rate limit will be applied to the Default Plan in the auto-generated Product, and will be shared across all the operations within the Plan.

   • Unlimited: Click this option to allow unrestricted calls.
   • Custom: Click this option to define a specified number of calls in a time period.

   If you selected an existing Product, the Target product rate limit option is disabled; instead, the rate limits that are configured in the selected Product and Plan are applied.

   Tip: You can also use the Gateway tab in the API flow to add a Rate Limit policy at any point in your API assembly flow, to define a more granular rate limit in the API's assembly.

   Target plan

   If you selected an existing Product, choose an associated Plan that a selected application can subscribe to, in order to consume the API.

   If you chose to publish to an auto-generated Product, the application is automatically subscribed to the Default Plan in this Product, and you cannot change this setting.

   Test application

   Select an application that you want to subscribe to the selected Plan, to consume the API.

   • Use the built-in Test Application: Click this option to use the pre-supplied test application. This option is available only if you chose to use the Sandbox Catalog.
   • Choose an existing Application: Click this option to select an existing application that was manually created in the selected Catalog. (If you have a Developer Portal site, this application will be registered in the portal that is associated with the selected Catalog.)

   Test consumer org

   The consumer organization that owns the selected application is displayed here by default.

   
7. Click Save to save your settings for enabling or disabling unified authoring.
   You can now start the flow.

After you have authored the flow to your requirements, and configured preferences for publishing the API to API Connect, start the flow so that you can observe its behavior.

To start your flow, set the Stopped/Started switch to on.

Notice that a Test tab is immediately added after the Gateway tab, to use for testing the API within App Connect Designer.

The OpenAPI 3.0 YAML definition for the running API flow in App Connect Designer is used to also automatically add and publish the API to a Product and Plan in the specified Catalog and provider org in your API Connect instance. The API Product also becomes visible in the Developer Portal if you have one configured.

Note: Based on your preferences, the API is added either to an auto-generated Product or to a standalone version of the existing Product that you selected. The published Product will contain only your API.

After the API is started, you can access your API Connect instance to view the published API in the API Manager and Developer Portal.

To access the API in API Connect, complete the following steps:

1. Open the API Manager UI in a new tab in your browser. For example, from the navigation menu , click Administration > Instances (or Administration > Integration instances) and then click the name of the API Connect (type API management) instance.
2. From the navigation pane, click the Manage icon .
3. From the Manage page, click the Sandbox or user-defined Catalog that you opted to publish to (if using App Connect Designer 12.0.5.0-r1-lts or later). If using an earlier App Connect Designer version, click the Sandbox Catalog.
   On the Products tab, you should see the published Product that contains the API. The Product title and name are derived from the name of the originating API flow, and also include a reference to App Connect Designer. The Product version is given as 0.0.1 if you chose to publish to an auto-generated Product, or is inherited if you chose to publish to (a standalone version of) an existing Product.

   • If you chose to publish to an auto-generated Product, the Product title is shown as API_flow_name (Created by App Connect Designer), and the name is shown as api-flow-name-created-by-app-connect-designer.
   • If you chose to publish to an existing Product, the Product title is shown as Product name - API_flow_name (Created by App Connect Designer), and the name is shown as product-name-api-flow-name-created-by-app-connect-designer.

   
4. Optional: To work with the API (in a limited capacity), click the options icon and then select the menu option that you require. For example, you can select Manage APIs to view the base endpoints for the API, or you can view subscriptions. You can also use the Analytics tab to view analytics about the API calls.
   Restriction: The API cannot be further developed in API Connect and will exist within the API Manager UI only while the corresponding API in App Connect Designer is still running. When you stop the API in App Connect Designer, the Product is automatically deleted from the Catalog.
5. Optional: If you have access to a Developer Portal that was enabled for the specified Catalog, use the Portal URL (under Catalog settings in the API Manager) to open the Developer Portal site.
   

   From the Developer Portal, click API Products to explore the published API Product.

   

   You can click the Product name or API name on the tile to view the Plan details or OpenAPI definition of the API, or to test the API. For example:

   

   For more information, see Exploring APIs and Products in the Developer Portal.

   Restriction: The API Product will exist in the Developer Portal only while the corresponding API in App Connect Designer is still running. When you stop the API in App Connect Designer, the API Product is automatically removed from the portal.

After the API is started, you can perform any of these tasks from your App Connect Designer instance:

• 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's options menu [⋮], you can stop, start, 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.

  

  Note:

  • When the unified authoring requirements are met, the behavior of the Start and Stop menu options is identical to the Stopped/Started switch in the API editor of the flow.
    • The Start menu option will add and publish the API to a Product in the selected Catalog. The settings that you configured from the API gateway settings panel in the API editor will be used to determine the API publishing preferences. (The Start menu option is available only if the flow is in a Stopped state and all of its nodes pass validation.)
      
    • The Stop menu option will delete the Product from the selected Catalog.
  • Although the generated API definition within the API editor conforms to the OpenAPI Specification Version 3.0, if you use the Export menu option to export your API flow as an OpenAPI document, the resulting YAML or JSON document can conform to either version 2.0 or 3.0 of the OpenAPI Specification based on your selection.
• Export the API flow and run it as an API in a production environment.
  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.