Creating flows for an API from scratch

To create an API flow, complete the following steps.

1. On the App Connect home page, click Create flows for an API.
   Alternatively, go to the App Connect Designer dashboard and click Create > Flows for an API.
   The API editor opens with three tabs.

   Designer

   Use the Designer tab to create models and operations for the API.

   OpenAPI

   Use the OpenAPI tab to see a representation of the API in a format that conforms to the OpenAPI 3.0 specification.

   Gateway

   If unified authoring is enabled, use the Gateway tab to see default settings that the gateway can use to call the published API in API Connect. You can also enforce extra API policies or configure gateway and portal settings for this API.

   If unified authoring is disabled, the Gateway tab provides instructions to enable it.

2. Optional: To enable unified authoring, go to the Designer tab, click Change API gateway settings , enable unified authoring, then click Save.
   When you enable unified authoring, you can see and edit the preferences for publishing your API document. These preferences are described in step 15.
3. Enter a name that identifies the purpose of your flow.
   

   Tip: If you're on the flow runs plan, the flow name can contain a maximum of 32 characters. When you deploy a flow on the flow runs plan, the deployment takes the name of the flow, and a deployment name can contain a maximum of 32 characters.

   As you progress with the flow, App Connect saves your changes automatically. If you move away from the flow, the flow is saved as a draft flow that you can complete at another time.
4. To create a model that defines the structure of an object that you want to work with, enter a name in Model name, then click Create model.
   For example, you might want a customer object that you can create, retrieve, or update records for.
   The model panel has two tabs.

   Properties

   Use the Properties tab to define the structure of the model.

   Operations

   Use the Operations tab to define how the API interacts with the model.

   
5. On the Properties tab, define the structure of the model by configuring properties.
   Note: Properties have the following requirements and restrictions.

   • Each property name must be unique.
   • The name must contain only letters, numbers, or the underscore character.
   • Spaces are not allowed in the name, but you can use an underscore character (_) to separate words.
   • The name must begin with a letter or an underscore.
   1. To add the first property, enter a name and select a data type for that property.
      By default, the first property that you add has the ID option selected. The flow must return the property that is designated as the ID for the model when it creates an object. The ID property must also be sent in a request to update or retrieve an object by using its ID. Set an ID against one property.

      Tip: To add a property from the applications that you're connected to, you can also click Select properties from applications. Select the appropriate account, select one or more properties, then click Add properties.

      
   2. To add more properties, click Add property.
      
6. Optional: To create more models, click Create model and add properties for each new model.
   To edit the name of a model or a delete a model, use the appropriate option from the menu.

   
7. To define how the API interacts with the model, click Operations.
   • To add one of the built-in operations, click Select an operation to add, then choose a Create, Retrieve, or Replace or create operation to run against the model.
     
   • If you choose an operation that involves a filter, select the appropriate filter properties. For the Retrieve model_name with filter operation, you can also enable and configure pagination settings for the results. Pagination allows your API to return a "page" of data each time the API is run. The limit parameter states how many records to return. The skip parameter specifies the number of records to skip before the flow starts to return records. The token parameter is a string that your API can use to identify where to start returning records from.
     To apply filters, you must define at least two properties, including the ID property for the model because the ID property cannot be selected as a filter.

     

     For more information, see Introducing filter parameters for API flows in IBM App Connect and Configuring pagination for the Retrieve with filter operation in API flows in the IBM Integration Community.

   • To define your own operations, click Select an operation to add, then select Add a custom operation.
     Restriction: The query parameter cannot be the same as the model ID, and the name of your custom operation cannot be any of the following 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

8. Configure a flow that implements the operation:
   1. Click Implement flow.
      

      The flow editor contains a basic flow structure that contains a Request node, a Response node, and a space to add one or more target applications, imported APIs, or toolbox utilities. The structure of the Request body example is constructed from the properties in your model, with some sample data.

      
   2. To add an application or imported API to the flow, click (+), select an application or API, then select an appropriate action.
      Ensure that the correct account is selected for App Connect to use to connect to the target application or API. If no accounts are connected, you can connect to one by following the instructions in Connecting to accounts. If you don't see a connector in the catalog for the action that you want to add, try searching for a community connector in the IBM Automation Explorer. You can also create a connector by using the Connector Developer Kit. For more information, see Adding or creating community connectors.
   3. Complete 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 input text, mappings, and JSONata expressions manually, or to define your own custom values, see Configuring actions.

      To populate the fields for the action automatically with suggested smart mappings, use Mapping Assist (see Simplifying data mapping and data transformation with AI-powered suggestions).

      

      Tip: You can use auto-generated or custom sample data to test the mappings as you add them. For more information, see Testing mappings with sample data. After you complete the fields for the action, you can also use sample data to test the action. To test the action, ensure that you're using a nonproduction account because the action is completed on the target application that you're connected to. For more information, see Testing actions with sample data.
   4. Optional: Add further applications or imported APIs.
   5. Optional: Use one or more supported toolbox utilities to provide specialized processing.
      For example, add an If node to provide conditional processing, or add 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 is returned when the operation completes successfully.
   7. In the Response header section, specify your preferred response status code.

      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 are 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 shows all the fields that you requested from the target application or API.

      After you configure all the nodes in the flow, you can use auto-generated or custom sample data to test the flow before you start it. Ensure that you use nonproduction accounts when you test your flow. The configured actions in the flow are completed on the target applications that you're connected to. For more information, see Testing a 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.
   
10. Define operations for any additional models and implement their flows.
11. Optional: You can add an error catch flow to handle errors in your API flow.
    For more information, see Configuring a catch flow to handle errors in your event-driven or API flows.
12. Before you test or deploy your flow, fix any validation errors in the flow.
    For more information, see Validating your flow.
13. Optional: To view the API definition for the flow, click the OpenAPI tab.
    The API definition is shown in the Form view , which is similar to the view where you edit APIs in API Connect. The details in this tab are read only, but are updated automatically when you change the models and operations for the flow in the API editor. The General category of the form view is expanded by default. The following categories are also available. (Some sections in this view are not currently applicable or don't display any details for the API.)

    The Components category displays reusable objects that relate to various aspects of the API definition.

    • Schemas displays details about each model and its properties.
    • Responses are not applicable.
    • Parameters are not applicable.
    • Examples are not applicable.
    • Request Bodies are not applicable.
    • Headers are not applicable.
    • Security Schemes displays details of the preconfigured API key security scheme that is 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 are not applicable.

    

    The General category contains the following sections.

    • The Info section contains the API summary. This section includes the flow name as the title, a generated name that is based on the flow name and that is used to identify the API, and an assigned version (typically 0.0.1). The remaining fields are blank.
    • The Servers section shows the server definitions in the API for connecting to a target server. When you test an API on the VPC hours plan, the API is deployed temporarily to the default integration runtime. Therefore, the API endpoint begins with https://default-integration-runtime; for example:

      https://default-integration-runtime-https-ac0abcd2def.p-vir-d1.appconnect.ibmappdomain.cloud/Bookstore_API

      When you deploy an API on the VPC hours plan, the API is deployed to the runtime that you create. Therefore, the API endpoint begins with the name of your runtime; for example:

      https://my-custom-ir-https-ac0abcd2def.p-vir-d1.appconnect.ibmappdomain.cloud/Bookstore_API

      If you're on the flow runs plan, the server URL starts with a forward slash (/), followed by the flow name with underscores (_) to replace spaces; for example, /Customer_API.
      
      
    • Security displays the security requirements that are enforced on the API. By default, a clientID security scheme of type apiKey is configured.
    • External Documentation is not applicable.
    • Tags are not applicable.

    

    The Paths category 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 navigation pane to explore further. This category contains the following sections.

    • Servers are not applicable.
    • Parameters are not applicable.
    • Operations shows details that are based on the operation type. For example, you might see 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 Source . This view is also read only, and the YAML source conforms to the OpenAPI 3.0 specification.

    
14. Optional: If unified authoring is enabled, click the Gateway tab to view and configure policies and gateway and portal settings. Any settings that you configure here affect the behavior of the API that is published in API Connect, but have no effect on the API that is running in App Connect.

    If unified authoring is disabled, go to step 16 to start the flow.

    Policies

    Use this view to see the assembly editor and 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. It also includes a slide-out property sheet that is used to configure an element, and a canvas that is used to arrange and visualize the elements of the assembly. For more information, see The assembly editor, API policies and logic constructs, and Handling errors in the assembly in the API Connect documentation.

    

    When you first open the Policies view, the canvas provides a single Invoke policy to run the API. The gateway can use this policy to call the running API in App Connect. You can click to open the property sheet for this policy. However, you don't need to edit any of the default settings, which also include a username and password for HTTP basic authentication. The app-connect-designer-url variable in the URL field represents the URL of the current App Connect instance, which the gateway needs 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 endpoint URL to call the API. The app-connect-designer-url defines the endpoint URL.

    

    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 a Rate limit policy into the correct position in the assembly. You can 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 a rate limit is defined in the assembly, it affects calls only 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 stopped 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 completed. Only the actions that appear in the flow after the rate limit policy are cancelled.

    

    Gateway and portal settings

    Use this panel to view general configuration settings for the API and 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 instance, which the gateway uses for access. Do not delete or edit this property.

    

15. Optional: If unified authoring is enabled, configure publishing preferences for API Connect.

    If unified authoring is disabled, go to step 16 to start the flow.

    You can configure or update publishing preferences only when the flow is stopped. The publishing preferences are associated with that flow only.

    If you start an API flow 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 were previously set, the API is published to the Default Plan in an auto-generated Product in a sandbox catalog in any of your discovered API Connect instances.

    1. On the Designer tab of the API editor, click the Change API gateway settings icon .
       
       The API gateway settings panel opens.

       

       Note: You can disable unified authoring on this panel if you don't want to publish your API flow automatically to API Connect. You can't disable unified authoring or update other preferences while the flow is running after it is started. You can view your selected preferences in read-only mode, but you must stop the flow if you want to update these preferences. When you stop the flow, the published API is deleted. After you restart the flow, the API is republished according to your updated preferences.
    2. The API management property is a read-only field with a value of API Connect. In API Connect, one provider organization is available for each instance. Therefore, use the Provider organization property to specify the API Connect instance to publish the API to.
    3. 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 host the published API.

       Target catalog

       Specify the catalog through 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 can't be enabled for this catalog. If you chose an existing catalog that is not partitioned into Spaces, the Target space option is also not displayed .

       Target gateway services

       Specify which Gateway services 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 are disabled.)

       
    4. 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 to 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 is 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 is applied to the Default Plan in the auto-generated Product, and is 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 assembly.

       Target plan

       If you selected an existing Product, choose an associated Plan that a selected application can subscribe to and 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 can't 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: Select 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: Select this option to select an existing application that was created manually in the selected catalog. (If you have a Developer Portal site, this application is 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.

       
    5. Click Save to save your settings.
       Your publishing preferences are preserved for the lifetime of the flow in App Connect. The preferences are retained when you stop and restart the API, or if you disable and then re-enable unified authoring.
16. You can run the flow so that you can observe its behavior.

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

1. In your API Connect instance, open the API Manager UI.
2. On the navigation pane, click the Manage icon .
3. On the Manage page, select the sandbox or user-defined catalog that you chose to publish to.
   On the Products tab, you can 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. If you chose to publish to an auto-generated Product, the Product version is given as 0.0.1. If you chose to publish to a stand-alone version of an existing Product, the Product version is inherited.

   • 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 select the appropriate menu option.
   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 can't be developed further in API Connect and exists in the API Manager UI only while the corresponding API in App Connect is running. When you stop the API in App Connect, 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 more information, see Exploring APIs and Products in the Developer Portal in the API Connect documentation.

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