Getting Started with APIs in Red Hat Integration

Red Hat Integration 2019-04

Getting Started with APIs in Red Hat Integration

Integration Documentation Team

Abstract

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

Preface

Use the Task API quickstart to learn how to develop and deploy REST APIs with Red Hat Integration.

Chapter 1. Overview

For developing and deploying REST APIs, 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 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.
Apicurito
Red Hat provides a lightweight version of the Apicurio Studio API designer, enabling you to create API definitions in OpenAPI (Swagger) format. Apicurtio is accessible within the Fuse Online API provider.
3scale API Management
With Red Hat 3scale API Management, API security, performance, control, and monetization are managed for you.
APIdiagram

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

Chapter 2. Configuration requirements

Before you can use Red Hat Integration to run the quickstart, 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.

  • For Fuse Online, the default behavior is that APIs are not exposed for automatic discovery in 3scale. The OpenShift administrator must configure Fuse Online to enable 3scale discovery.

    To verify this setting (you need OpenShift administrator permissions):

    1. In OpenShift, open the Fuse Online project.
    2. Select Applications> Deployments, and then select syndesis-server.
    3. Click the Environment tab.
    4. Verify that the CONTROLLERS_EXPOSE_VIA3SCALE variable is set to true.

  • The published API service must have the correct 3scale annotations.

    Fuse Online automatically adds the correct annotations if the CONTROLLERS_EXPOSE_VIA3SCALE environment variable is set to true before you publish the API.

  • The 3scale API Management administrator must configure 3scale for service discovery.

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

The Task Management API quickstart helps you to quickly learn how to configure, publish, and test an API provider integration.

The Task Management API example simulates a simple API that sales consultants might use to track the tasks that they need to do when interacting with customer contacts. Example "to-do" tasks might be "create an account for a new contact" or "place an order for an existing contact".

3.1. Overview of steps for the Quickstart

  1. Optionally, if you want to view the API in the Apicurito web-based designer, import the provided OpenAPI JSON file.
  2. Import the provided ZIP file and edit the API operation return codes.
  3. Publish the Fuse Online integration as an API service to make it available on OpenShift.
  4. In 3scale API Management, discover the published API service.

3.2. Before you begin

Go to https://github.com/syndesisio/syndesis-quickstarts/tree/master/api-provider and download task-api.json and TaskAPI-export.zip.

3.3. Viewing the API in Apicurito

  1. In Fuse Online, in the left navigation panel, click Integrations.
  2. Click Create Integration.
  3. For the Start Connection, click the API Provider card.
  4. For the Upload an OpenAPI file, drag and drop the task-api.json file that you downloaded. Fuse Online indicates that it has successfully imported the file.
  5. Click Next.

  6. Click Review/Edit.

    The API opens in Apicurito.

  7. Explore the structure of the API. Note that it has two paths - one for tasks and one for a specific task - and three operations to create a task, retrieve a task by its ID, and delete a task by its ID.

    To save time, rather than building the integration from the OpenAPI specification, you can use the already built integration that is also provided with the quickstart download.

  8. Cancel and confirm the cancellation until you return to the Fuse Online dashboard.

3.4. Importing and completing the Task API integration in Fuse Online

  1. To import the quickstart:

    1. In Fuse Online, in the left navigation panel, click Integrations.
    2. In the upper right, click Import.
    3. Drag and drop the TaskAPI-export.zip file that you downloaded. Fuse Online indicates that it has successfully imported the file.

  2. In the left navigation panel, click Integrations to see an entry for the Task API integration that you just imported. The entry indicates that configuration is required.

    Connections and steps have already been added to this flow. In the operation flow visualization panel on the left, move your cursor over the icons to see what they represent. Click a step to view its configuration. When you are done examining one, click another one to examine it. When you click a database connection, you can see the SQL statement that it executes.

  3. To open the integration editor:

    1. Click the Task API entry to display its summary.
    2. In the upper right, click Edit Integration to display a list of the operations that this API provides.

  4. To configure the flow for the Create Task operation:

    1. Click the POST entry for the Create Task operation.
    2. In the operation flow visualization panel on the left, click the Provided API Return Path icon at the bottom. You might have to scroll down to see it. When you hover over it, Fuse Online displays Provided API Return Path.
    3. Click the Return Code input field and scroll to select 201 Created.
    4. Click Next, and then click Save.
    5. At the top, to the right of Operations, click the down arrow and then click Go to Operations List.
  5. Repeat step 4 for the Delete and Get operations to change the return codes from 501 to 200.

3.5. Publishing the integration in Fuse Online

  1. Save the integration.

  2. In the upper right, click Publish.

    Fuse Online displays the integrations list page and shows publication progress as it assemblies, builds, deploys, and starts the integration.

When the entry for the Task API integration displays Running, it is available for discovery by 3scale.

3.6. Discovering the published API in 3scale

  1. Log in to the 3scale Administration Portal.
  2. From the Admin Portal’s Dashboard, click New API.
  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.

3.7. Next steps

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

Legal Notice

Copyright © 2019 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.