Creating flows for an API from scratch
You can create flows for an API (alternatively referred to as an API flow) in App Connect Designer. The defined configuration provides an API that exposes one or more operations. You can use these operations to call out to an endpoint and pass data between that endpoint and applications in the flow.
Before you begin
- If you know which applications or imported APIs you need, create accounts in the App Connect Designer catalog for the connectors that run API operations against the target applications or APIs. You can also create accounts when you create a flow. For more information, see Connecting to accounts.
- To use unified authoring
to create API flows that you can manage in IBM® API Connect, ensure that
you meet the following requirements.
- You must have an instance of IBM API Connect Enterprise as a Service in the same region as your IBM App Connect Enterprise as a Service instance. If you have an existing trial instance of App Connect, you can provision an API Connect trial instance in the same region. To provision a trial instance of API Connect Enterprise as a Service from the App Connect Designer home page, click Manage API flows by using IBM API Connect.
- Your API Connect instance must be configured with at least one registered DataPower API Gateway service.
- Your API Connect instance must contain at least one provider organization that you are authorized to access. The provider organization must include a catalog that contains an application with an owning consumer organization and a client ID.
- Ensure that unified authoring is enabled for your instance. On the Designer tab of the API flow editor, click the Change API gateway settings icon , then enable unified authoring.
About this task
When you create flows for an API, each individual flow is the implementation for an API operation that is typically called from mobile and web applications. (Examples of operations are 'GET order' and 'POST order'.) The flow for each operation contains a request, actions for one or more applications or imported APIs, and a response for the API operation. The flow might also contain toolbox nodes for specialized data processing. 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 completes its action. The flow then returns a response that either confirms that the actions were successful, or returns the data that was requested.
- You create one or more models that define the structure of the objects that you want to create or retrieve. You can create up to 10 models.
- You choose the built-in create, retrieve, or replace or update operations to complete against each model, or you define your own custom operations.
- You configure a flow to implement each operation and add actions for one or more target applications or APIs. You might also add toolbox utilities to the flow to process the input or output data from these applications.
If you have an instance of API Connect in the same region as your App Connect instance, you can expose your API in both App Connect Designer and API Connect. This feature is known as unified authoring. Unified authoring is enabled by default if at least one API Connect instance exists in the same region with Developer or higher access.
With unified authoring, when you create and start an API flow in your Designer instance, the API is added automatically to a Product. That Product is then published in a catalog that is provided for a provider organization in API Connect. The Product also becomes visible on the API Connect Developer Portal if a site is enabled for the catalog. The publishing preferences are based on the user who is logged in. App Connect automatically discovers the provider organizations in API Connect that the user has access to in the same region as the App Connect instance. You can specify settings for publishing the API to a preferred API Connect instance and provider organization. You can also choose catalog and Gateway targets, the containing Product and Plan for the published API, and a consuming application.
You can work with the API in API Connect independently of the one in App Connect Designer. You can also browse the Product (and API) in the Developer Portal. When you stop the API in App Connect Designer, the Product (and API) in the API Manager user interface and the Developer Portal site are deleted automatically. (A user who doesn't have access to API Connect can stop the flow in App Connect. However, the API remains published in API Connect.)
If you have an instance of IBM API Connect Enterprise as a Service in the same region as your IBM App Connect Enterprise as a Service instance, unified authoring is enabled by default. Therefore, if you create and start an API flow, it is published automatically to API Connect. If you start an API flow without specifying publishing preferences, 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. If you don't want to publish APIs automatically to API Connect, you can disable unified authoring. On the Designer tab of the API editor, click the Change API gateway settings icon , set unified authoring to disabled, then click Save.
Creating the API flow in App Connect
Procedure
To create an API flow, complete the following steps.
Accessing the published API in API Connect
About this task
Procedure
To access the API in API Connect, complete the following steps.
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. If the flow is working correctly, you can see the response from the target applications in the test facility. You 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, where you can see the tile
for your API flow. From the flow options menu [⋮], you can stop, start, export, or delete the API flow. While the API flow is running, you can also open it to view the configuration, but you must 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 adds and publishes the API to a Product in the
selected catalog. The settings that you configured from the API gateway
settings panel in the API editor are 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 deletes the Product from the selected catalog.
The generated API definition in the API editor conforms to the OpenAPI Specification Version 3.0. However, 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.
- The Start menu option adds and publishes the API to a Product in the
selected catalog. The settings that you configured from the API gateway
settings panel in the API editor are 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.)
- To run your API flow, export it and deploy it to an integration runtime in the App Connect Dashboard.
- After you test the flow successfully in App Connect Designer, export the flow as a broker archive (BAR) file, which packages the integration.
- Upload the BAR file to the App Connect Dashboard, then deploy the file to an integration runtime to run the integration in the production system.