Using APIs

APIs in IBM® Concert Workflows®

In IBM Concert Workflows®, APIs are the mechanism by which you deploy a workflow, that is, make it callable from outside the application. Structurally, APIs are collections of endpoints that are organized into one or more stages.

Stages are parallel versions of an API that you can use for different purposes. For example, if you want to make the same API available in development, QA, and production environments, you might create three stages that are called dev, qa, and prod.

Endpoints are subpaths that are appended to an API's URL paths as unique identifiers. For example, you might want to create two APIs in the prod stage so that you can deploy two different workflows. To create the two APIs, you first create two endpoints, for example, foo and bar. You can then deploy one workflow on the /api-1/prod/foo path and deploy the other on the /api-1/prod/bar path. Within the prod stage, the /foo and /bar endpoints uniquely identify the APIs.

To deploy a workflow, you associate an API with a stage and an endpoint. This combination of API, stage, and endpoint determines the unique URL on which you deploy the workflow. After the workflow is deployed, the URL does not change even if you change the workflow's name.

Each API and stage can use different endpoints that support basic HTTP methods, such as GET and POST.

When you create an endpoint, it is made available in all stages. For example, if you create an endpoint called test, you can use this endpoint to deploy different workflows on all of your stages. You can deploy one workflow on the /api-1/prod/test path, another on the /api-1/qa/test path, and another on the /api-1/dev/test path. As a result, APIs are considered key to maintaining a unique API gateway system that is designed to provide external and internal access to the application environment.

Deployed workflows are considered to be active and count toward your license. You can check the relevant limitations for your account in the About page.

But before you deploy a workflow, you must create an API. Make sure that you have permission to view and interact with the APIs page.

Creating APIs

1. Open the APIs page.
   1. If you are connected to another application, click Workflows.
   2. In the IBM Concert Workflows® sidebar, click APIs.

   The APIs page opens and the list of APIs is shown. You can search and sort APIs. If you have the required permissions, you can view shared APIs in the Shared folder or create APIs on behalf of the user who delegated the permissions to you.

2. Click + Create API.
3. In the Create API dialog, give the API a name.
4. In the General settings section, select a worker group to run the API's associated workflow. You can optionally provide an API description.
5. In the Authentications section, configure an authentication policy to control which users can access the API.

   Table 1. Authentication policy

   Authentication policy	Meaning
   IBM Concert Workflows®	Only logged-in users can access the API. You can then choose one of these options: Allow access to only your user when you are logged in. Allow access to every logged-in user. Allow access to only certain users and roles.
   Anonymous	Anyone that has the URL can access the API.
   API keys	Anyone that has the URL and a specific API key can access the API. To create a unique API key, click + Add API key. To use API key authentication, complete these steps: In the Send API key via field, select one of these authentication mechanisms: Query parameter (default) Authorization header Custom header Cookie Specify the delivery mechanism value in the adjacent field. The default values are: Query parameter: api_key. Authorization header: ApiKey. Custom header: X-API-Key. Cookie: X-API-KEY. You can replace the default identifier (such as query parameter name, authorization header value, custom header name or cookie name) with a custom value. The custom value must match the required format, for example: QUERY_PARAM_NAME: /^[a-z0-9._-]+$/, API_KEY_HEADER_NAME: /^[A-Za-z0-9-]+$/ If the identifier value does not match the validation pattern, an error message is displayed. A notification displays the selected authentication mechanism and its value. Optional: Click the Learn how to use it link to view examples of how customers must specify the authentication delivery mechanism in their API requests.
   Workflow	Select a separate deployed authentication workflow that determines the set of users who can access the API. You cannot choose this option without creating your API first. When you choose this option, you must specify the stage and endpoint where this authentication workflow runs. For more information, see Workflow authentication (API gateway).

6. In the Network Access Control List (NACL) section, configure settings that control which IP addresses and networks can access the API.

   Table 2. Setting to access the API

   Setting	More information
   Disable NACL and allow all	Select this checkbox to allow all network traffic to access this API.
   Rules to allow or deny traffic from source networks/IPs	Create a rule for each network or IP address that you want to control access for, then configure these settings: Disable Select this checkbox to disable the rule. IP Network Specify the IP address or network that the access applies to. Access To allow the IP address or network to access the API, select Allow. To deny access, select Deny.
   Allow access if no rule matches	Click this radio button to allow all IP addresses and networks that are not included in the list of rules to access the API.
   Deny access if no rule matches	Click this radio button to prevent all IP addresses and networks that are not included in the list of rules from accessing the API.

   Note: If incoming requests to your API server are forwarded through an HTTP proxy or load balancer, ensure that the proxy or load balancer includes the X-Forwarded-For HTTP header in the forwarded requests. This header identifies the originating IP address of the request. For more information, see X-Forwarded-For.
7. Optional: In the Advanced settings section, configure overridable settings that apply to all elements of the API.

   Table 3. Settings to override

   Setting	More information
   Workflow response mode	Indicate whether the workflow will run synchronously or asynchronously.
   Workflow logs	Indicate whether you want logs to be generated when the workflow runs.
   Response timeout (in ms)	Specify the time interval after which communication between the worker and API is lost.
   Message timeout (in ms)	Specify the time interval after which a message indicates that all jobs that the worker is running will be killed.
   Error status code	Specify the numerical HTTP response status code that is returned when the workflow completes with an error.
   Include statistics	Indicate whether you want the following properties to be returned in the API's response: "$uuid": "<unique ID of flow execution>", "$runner": "<unique ID of worker running the workflow>", "$status": "C", "$met": 0, "$stats": { "timeStarted": <workflow start time>, "timeEnded": <workflow end time> }
   Enable API request logging	Indicate whether requests to run the deployed API endpoints will be logged. Note: When you no longer need to log API requests, clear this option to ensure that logs are not created unnecessarily.

8. Click Create.

   The Workflow Deployment module opens. You can now deploy the API by associating it with an endpoint and stage. For API deployment steps, see Deploying workflows.

Optional actions