Chapter 2. Viewing, publishing, and discovering the Task API quickstart

2.1. Before you begin

Before you can use Red Hat Integration to run the Task Management API Provider quickstart integration, make sure that your OpenShift environment meets the following configuration requirements:

2.2. Overview of the Quickstart

In Red Hat Integration, a quickstart (sometimes called a booster) is an example integration that you can import into your Fuse Online environment.

The Task Management API Provider quickstart helps you to quickly learn how to configure, publish, and test an API provider integration. It simulates an API that sales consultants might use to track the tasks that they must complete when interacting with customer contacts. Some example "to-do" tasks include "create an account for a new contact" or "place an order for an existing contact".

2.2.1. Overview of steps for using the Quickstart

  1. Download the Task Management API Provider quickstart files.
  2. (Optional) View the API definition in API Designer by importing the quickstart OpenAPI JSON file.
  3. Import the quickstart ZIP file into Fuse Online and then publish it.
  4. Discover the published API service in 3scale API Management.

2.3. Downloading the Task Management API Provider quickstart files

You must download the Task Management API Provider quickstart files so that you can import them into Fuse Online.

Go to https://github.com/syndesisio/syndesis-quickstarts/tree/1.10/api-provider and then download these files:

task-api.json (raw)

The Task Management API definition in OpenAPI format. You view this file in the API Designer to explore the API structure. The API definition is a starting point for an API Provider integration.

Note

You must download the raw version of this file.

TaskAPI-export.zip
The Task Management API Provider integration. This file contains the complete API Provider integration (based on the API definition in the task-api.json file). You import this file into Fuse Online, edit it in the Fuse Online integration editor, and then publish it as an API service that 3scale can discover.

2.4. Viewing the API definition in API Designer (optional)

You can use the API Designer to create new API definitions in OpenAPI (Swagger) format. You can also use the API Designer to view and edit existing API definitions. You can use an API that you create or import into the API Designer as a starting point for building a Fuse Online integration.

This task is optional because you use the API Designer to peruse the Task Management API paths, operations, and data type (that is, you are not creating or editing the API specification). After you become familiar with the API specification, you exit the API Designer and return to Fuse Online to import the pre-built integration that is provided in the other quickstart file (TaskAPI-export.zip).

Prequisite

Procedure

Follow these steps to view the API definition in the API Designer:

  1. In Fuse Online, in the left navigation panel, click Integrations.
  2. Click Create Integration.
  3. On the Choose a connection page, click the API Provider card.
  4. Drag the raw version of the task-api.json file that you downloaded to the Upload an OpenAPI file section. Fuse Online displays a message that it has successfully imported the file.
  5. Click Next.

    Note

    You can safely ignore the warning messages.

  6. Click Review/Edit.

    The API opens in API Designer.

  7. Explore the structure of the API. It includes the following components:

    • Two paths (/ and /{id}) with these operations:

      • GET - Get a list of all tasks
      • POST - Create a new task
      • GET - Fetch a task by its ID
      • PUT - Update a task by its ID
      • DELETE - Delete a task by its ID
    • The Task data type
  8. To save time, rather than building the integration from this OpenAPI specification, you exit the API Designer and return to Fuse Online so that you can import the entire pre-built integration that is provided in the other quickstart file (TaskAPI-export.zip) that you downloaded in Section 2.3, “Downloading the Task Management API Provider quickstart files”.

    To exit the API Designer, click Cancel three times and then Confirm the cancellation until you return to the Fuse Online dashboard.

2.5. Importing and publishing the example API provider quickstart integration

The TaskAPI-export.zip file contains the Task Management API Provider integration. It is based on the API definition in the task-api.json file.

After importing the quickstart integration, you can examine the operation flows and then publish the integration.

Prerequisites

  • Fuse Online is open in a browser.

Procedure

  1. Import the TaskAPI quickstart integration:

    1. In Fuse Online, in the left navigation panel, click Integrations.
    2. Click Import.
    3. Drag the TaskAPI-export.zip file that you downloaded to the Import page. Fuse Online indicates that it has successfully imported the file.
    4. In the left navigation panel, click Integrations to see an entry for the TaskAPI integration that you just imported. Although the entry indicates that configuration is required, this integration is ready to publish.
  2. In the TaskAPI entry, click Three Vertical Dots and then click Edit to display a list of the operations that this API provides.

    Each operation has a flow defined for it. In Fuse Online, a flow defines the connections and other steps to execute for each REST operation in the integration. The imported quickstart provides pre-defined flows for each operation.

  3. To examine the flows for each operation:

    1. Click its Edit flow button to display the visualization for that flow.

      Each flow already has a database connection, one or more data mapper steps, and a Provided API Return Path step that finishes the flow.

    2. For the Invoke SQL step, click Configure to see the SQL statement that the connection executes. Then click Cancel to return to that operation’s visualization flow.
    3. For a data mapper step, click Configure to see the mappings. Then click Cancel to return to the visualization.
    4. For the Provided API Return Path step, which is the last step in every operation’s flow, click Configure to see the HTTP return codes that the operation might send to the caller. Click Cancel to return to the visualization.
    5. After examining one operation’s flow, click the Integrations> TaskAPI> Operation drop down menu and then select another operation.
    6. Repeat this subset of steps to examine each flow.
  4. After examining the flows, click Publish, edit the integration name if you want to, and then click Save and publish.

    Fuse Online displays the summary page for this integration and shows publication progress as it assembles, builds, deploys, and starts the integration.

When 3scale service discovery is enabled, Red Hat 3scale publishes your API provider integration, which means that 3scale controls access to the integration’s API. Next, you use 3scale API management to discover the published API.

Note

If you want Fuse Online to publish the API service and provide a URL (for example, to test the API before you discover it in 3scale), you can disable discovery for the API provider integration as described in Developing and Deploying API Provider Integrations.

2.6. Discovering the published API in 3scale

After you publish an API service in Fuse Online, you can discover in 3scale API management.

  1. Log in to the 3scale Administration Portal.
  2. In the Admin Portal’s dashboard, click New Product.
  3. Choose Import from OpenShift.
  4. In the Namespace field, specify or select the OpenShift project that contains the API, for example fuse.
  5. In the Name field, type or select the name of an OpenShift service within that namespace, for example i-task-api.
  6. Click Create Product.
  7. Wait for the new API service to be asynchronously imported into 3scale. A message appears in the upper right section of the Admin Portal: The service will be imported shortly. You will receive a notification when it is done.

2.7. Next steps

See the Red Hat 3scale API Management documentation for information about managing the API.