Getting Started with APIs in Red Hat Integration

Red Hat Integration 2019-07

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. Apicurito 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. Viewing, publishing, and discovering the Task API quickstart

2.1. About the 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".

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

2.3. Before you begin

Go to https://github.com/syndesisio/syndesis-quickstarts/tree/1.7 and download these two files:

  • task-api.json
  • TaskAPI-export.zip

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

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

  • 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. You need OpenShift administrator permissions to verify this setting as follows:

    • On OpenShift 4.x:

      1. In OpenShift, open the Fuse Online project.
      2. On the Project Status page, select syndesis-server.
      3. Select Actions > Edit Environment.
      4. On the Environment page, verify that the CONTROLLERS_EXPOSE_VIA3SCALE variable is set to true.

    • On OpenShift 3.11:

      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.

2.5. Viewing the API in Apicurito (optional)

  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. For the Upload an OpenAPI file option, 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.

    • It has two paths:

      • /todo for tasks
      • /todo/{id} for a specific task

    • And three operations:

      • Create a task
      • Get a task by its ID
      • 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.

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

  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 shows a message to indicate that it has successfully imported the file.
  4. 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.

  5. Open the integration editor:

    1. In the row for the Task API entry, select the menu icon .
    2. Click Edit to display a list of the operations that the API provides.

  6. Configure the flow for the Create Task operation:

    1. In the row for the POST operation, click Create flow.
    2. In the operation flow visualization panel, scroll down to Provided API Return Path at the end of the flow.
    3. Click Configure.
    4. For the Return Code field, select 201 Created.
    5. Click Next.
    6. Return to the list of operations by selecting Task API at the top of the page.
  7. Repeat step 6 for the Delete and Get operations to change the return codes from 501 to 200.

2.7. Publishing the integration in Fuse Online

  1. Click Save.

  2. On the Save the integration page, accept the default Name and click Save and publish.

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

When the Published message appears, the API is available for discovery by 3scale.

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

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