Chapter 1. Overview of Developing and Deploying API Provider Integrations

An application programming interface (API) is a set of tools, definitions, and protocols for building application software. An API lets products or services communicate with other products and services without having to know how they are implemented.

As a business user who wants to share data between different applications and services, you can use the Red Hat Integration distributed integration platform to:

  • Develop an API provider integration and connect to REST APIs.
  • Create applications that consume the data or functionality exposed by REST APIs.
  • Connect to products and services, including legacy systems and the Internet of Things (IoT).
  • Open up access to your resources while maintaining security and control. How you open access and to whom is up to you.

Red Hat Integration is a set of agile and flexible integration and messaging technologies that are designed to provide API connectivity, data transformation, service composition and orchestration, real-time messaging, cross-datacenter message streaming, and API management to connect applications across hybrid cloud architectures and enable API-centric business services.

Red Hat Integration includes the following products:

Fuse Online
Red Hat Fuse is a distributed, cloud-native integration platform. Fuse Online is Red Hat’s web-based Fuse distribution. It is provided pre-installed on the OpenShift Online Professional tier (and also available for installing on an on premise OpenShift cluster). Fuse Online is for business users who prefer low code development.
API Designer
Red Hat provides this lightweight version of Apicurio (https://www.apicur.io/) , enabling you to create API definitions in OpenAPI format. The API Designer is accessible within Fuse Online when you edit an API provider integration.
3scale API Management
With Red Hat 3scale API Management, you can set access policies, centralize control, and provide high availability for your APIs.

Prerequisites

You should have working knowledge of the following concepts:

  • Fuse Online concepts
  • REST API concepts
  • 3scale API Management concepts

Overview of steps

  1. In Fuse Online, create an integration that is triggered by an API call.

    1. Start the integration with a REST API service. Specify an existing REST API definition or create a new one in the API designer.

      Fuse Online creates an execution path, referred to as an integration flow, for each REST API operation.

    2. In each operation’s flow, add the connections and other steps that execute that operation.

      Each REST API client call invokes an operation and triggers execution of only the integration flow that executes that operation.

    3. Publish the Fuse Online integration, which makes it available as an API service on OpenShift.
  2. In 3scale API Management, discover the published API service. You can then secure the API, configure access policies, and launch it.

1.1. Benefit, overview, and workflow for creating API provider integrations

An API provider integration starts with a REST API service. This REST API service is defined by an OpenAPI 3 (or 2) document that you provide when you create an API provider integration. After you publish an API provider integration, Fuse Online deploys the REST API service on OpenShift. The benefit of an API provider integration is that REST API clients can invoke calls that trigger execution of the integration.

Multiple execution flows

An API provider integration has multiple execution paths, referred to as flows. Each operation that the OpenAPI document defines has its own flow. In Fuse Online, for each operation that the OpenAPI document defines, you add connections and other steps to the execution flow for that operation. These steps process the data as required for the particular operation.

Example execution flow

For example, consider a human resources application that calls a REST API service that Fuse Online has made available. Suppose the call invokes the operation that adds a new employee. The operation flow that handles this call could:

  • Connect to an application that creates an expense report for new employee equipment.
  • Connect to a SQL database to add an internal ticket for setting up new equipment.
  • Connect to Google mail to send a message to the new employee that provides orientation information.

Ways to trigger execution

There are many ways to call the REST APIs that trigger integration execution, including:

  • A web browser page that takes data input and generates the call.
  • An application that explicitly calls the REST APIs, such as the curl utility.
  • Other APIs that call the REST API, for example, a webhook.

Ways to edit a flow

For each operation, you can edit its flow by:

  • Adding connections to the applications that need to process the data.
  • Adding steps between connections, including split, aggregate, and data mapping steps.
  • Mapping connection error messages to return codes in the HTTP response that finishes the flow. The response goes to the application that invoked the call that triggered execution of the integration.

Workflow for creating an API provider integration

The general workflow for creating an API provider integration is shown in the following diagram:

General workflow for creating an API provider integration

Publishing an API provider integration

After you publish an API provider integration, in the integration’s summary page, Fuse Online displays the external URL for your REST API service. This external URL is the base URL that clients use to call your REST API services.

For Fuse Online environments on OCP, Red Hat 3scale discovery of API provider integrations might be enabled. In this case, 3scale publishes the URL for invoking services.

Testing an API provider integration

To test an API provider integration’s flows, you can use the curl utility. For example, the following curl command triggers execution of the flow for the Get Task by ID operation for the REST API service URL: https://i-task-api-proj319352.6a63.fuse-ignite.openshiftapps.com/api/.

The HTTP GET command is the default request so there is no requirement to specify GET. The last part of the URL specifies the ID of the task to get: 

curl -k https://i-task-api-proj319352.6a63.fuse-ignite.openshiftapps.com/api/todo/1

1.2. How OpenAPI operations relate to API provider integration flows

An API provider integration’s OpenAPI document defines the operations that REST API clients can call. Each OpenAPI operation has its own API provider integration flow. Consequently, each operation can also have its own REST API service URL. Each URL is defined by the API service’s base URL and optionally by a subpath. REST API calls specify an operation’s URL to trigger execution of the flow for that operation.

Your OpenAPI document determines which HTTP verbs (such as GET, POST, DELETE and so on) you can specify in calls to your REST API service URLs. Examples of calls to API provider URLs are in the instructions for trying out the API provider quickstart example.

Your OpenAPI document also determines the possible HTTP status codes that an operation can return. An operation’s return path can handle only the responses that the OpenAPI document defines. For example, an operation that deletes an object based on its ID might define these possible responses: 

"responses": {
  "204": {
           "description": "Task deleted"
         },
  "404": {
           "description": "No Record found with this ID"
         },
  "500": {
            "description": "Server Error"
        }
}

Illustration of an API provider integration example

The following diagram shows an API provider integration that processes data about people. An external REST API client invokes the REST API URLs that are deployed by the API provider integration. Invocation of a URL triggers execution of the flow for one REST operation. This API provider integration has 3 flows. Each flow can use any connection or step that is available in Fuse Online. The REST API along with its flows is one Fuse Online API provider integration, which is deployed in one OpenShift pod.

API provider integration with 3 flows

Editing the OpenAPI document while creating an API provider integration

After you specify an OpenAPI document for your API provider integration, you can update the document as needed while you define the execution flows for the API operations. To do this, click View/Edit API Definition in the upper right of a page in which you are editing the API provider integration. This displays your OpenAPI document in the API Designer editor. Edit and save the document to make changes that are reflected in Fuse Online.

Considerations while editing the OpenAPI document:

  • operationId properties for synchronization

    Synchronization between the versions of the OpenAPI document in the API Designer editor and in the Fuse Online integration editor depend on a unique operationId property that is assigned to each operation that is defined in the document. You can assign a specific operationId property value to each operation, or use the one that Fuse Online generates automatically.

  • Request and response definitions

    In each operation’s definition, you can supply a JSON schema that defines the operation’s request and response. Fuse Online uses the JSON schema:

    • As the basis for the operation’s input and output data shapes
    • To display operation fields in the data mapper

  • No cyclic schema references

    A JSON schema for an API provider integration operation cannot have cyclic schema references. For example, a JSON schema that specifies a request or response body cannot reference itself as a whole nor reference any part of itself through intermediate JSON schemas.