Getting Started with APIs in Red Hat Integration

Red Hat Integration 2019-12

Getting Started with APIs in Red Hat Integration

Integration Documentation Team

Abstract

Use the Task Management API Provider quickstart (booster) to learn how to develop and deploy REST APIs using Red Hat Fuse Online, Apicurito, and 3scale API Management.

Preface

Use the Task Management API Provider quickstart (an example that you import) to learn how to develop and deploy REST APIs with Red Hat Integration.

Chapter 1. Overview of Red Hat Integration components

For developing and deploying REST APIs, you can use these Red Hat Integration components:

Fuse Online
Red Hat Fuse is a distributed, cloud-native integration platform. Fuse Online is Red Hat’s web-based Fuse distribution. It is pre-installed on the OpenShift Online Professional tier. You can also install it on an OpenShift (on-premise) cluster. Fuse Online is for business users who prefer minimal code development.
API Designer
Red Hat provides a lightweight version of the API designer. You can use it to create API definitions in OpenAPI (Swagger) format. You can access the API Designer from within the Fuse Online API provider.
3scale API Management
Red Hat 3scale API Management manages security, performance, control, and monetization for your APIs.
APIdiagram

For more details, see Developing and Deploying APIs with Red Hat Integration.

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:

  • Your OpenShift Container Platform (OCP) on premise administrator must deploy Fuse Online and 3scale API Management on the same cluster.
  • The 3scale API Management administrator must configure 3scale for service discovery.
  • In Fuse Online, by default APIs are not exposed for automatic discovery in 3scale. In your OpenShift project where Fuse Online is installed, you must enable 3scale discovery by setting the OPENSHIFT_MANAGEMENT_URL_FOR3SCALE environment variable to the URL for your 3scale user interface.

    When you enable 3scale discovery, Fuse Online automatically adds the necessary 3scale annotations to the API.

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.8/api-provider and then download these files:

task-api.json (raw)

The Task Management API definition in OpenAPI (Swagger) 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 two warning messages.

  6. Click Review/Edit.

    The API opens in API Designer.

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

    • The Task data type
    • The /todo task with these operations:

      • Get a list of all tasks
      • Create a task
    • The /todo/{id} task with these operations:

      • Get a task by its ID
      • Update a task by its ID
      • Delete a task by its ID
  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. In the upper right, 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 Create 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 APIs with Red Hat Integration.

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 Service.
  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.

Legal Notice

Copyright © 2020 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.