Share, secure, and publish APIs using Red Hat OpenShift API Management 

Getting Started with Red Hat OpenShift API Management

Picture this: Your team has finished building out your brand new REST API. The tests are passing, and you’re confident that it will reliably hit your throughput targets. Internal teams are already successfully using it to add new functionality.

A new business requirement arrives a few weeks later. Management wants to enable API access for customers and partners. You realize that this is a non-trivial task that requires the implementation of proxies, security policies, rate limiting, logging, metrics, and an API portal for sign-up and documentation.

Design principles, such as the separation of concerns, indicate that this new functionality should be implemented separately from core API functionality. This is where you should reach for an API Management solution, which can provide an out-of-the-box solution for these new requirements.

In this tutorial, you will learn how to allow customers and partners to access your API in a secure fashion.  You can achieve this with ease using Red Hat OpenShift API Manager, which installs and manages instances of Red Hat 3scale API Management for you. 

This activity will guide you through the process of gaining access to an OpenShift API Management sandbox, deploying a sample Quarkus application to OpenShift, of importing it into Red Hat 3scale API Management using Service Discovery, and of protecting the API using an API Key security.

Here's a broad overview of what this process entails:

1. Launch the OpenShift API Management sandbox.
2. Access your Red Hat OpenShift API Management portal.
3. Deploy a containerized application that exposes an HTTP API.
4. Annotate the application for integration with Red Hat OpenShift API Management.
5. Secure and manage your HTTP API using Red Hat OpenShift API Management.

Sign up for a free Red Hat ​​OpenShift API Management sandbox

The first step is to sign up for your free trial Red Hat ​​OpenShift API Management sandbox. It's a simple process: there's no charge or credit card number required, and it's a nice way to start experimenting without installing anything. Just click the red button at the top of the page. This is, truly, the cloud at its best. 

Launch the OpenShift API Management sandbox environment

 Here is how to launch the OpenShift API Management tenant that has been  pre-provisioned in your sandbox environment.

1. Launch the sandbox and log in with your registered username and password. The sandbox takes you to the OpenShift console (Figure 1).

2. Two projects have been automatically created for you. From the Projects drop-down menu on the top of the page, set the project namespace to <username>-dev. The tenant is created within this <username>-dev project namespace. 
3. Note: You can view this tenant named dev-tenant by navigating to Search > Resources > Search for APIManagementTenant from the left-hand navigation.
4. Select Project. 
5. On the Project page under the launcher section. you will see a link API Management. Note: If you don’t see the link yet, please allow a few minutes before refreshing the page to access OpenShift API Management. Creation of this tenant takes a few minutes. 
6. Click on this link to launch your tenant for OpenShift API Management. (Figure 2)

 

Deploy a REST API on the sandbox

At this point of this tutorial, we have set up an OpenShift API Management Tenant on the OpenShift sandbox.

In this section, we will deploy an existing  Quarkus application in a container image and configure it to make it easily discoverable by OpenShift API Management.

First, let’s deploy an existing Quarkus application. The container image of this file is hosted on Quay, a registry for storing and building container images as well as distributing other artifacts conforming to Open Container Initiative (OCI) specifications. The Quay service is free for those who want to set up their own public repositories and available for a fee if you want to create private repositories.

This is how you can deploy the Quarkus application on OpenShift:

1. Click the perspective switcher at the top of the navigation of the OpenShift console, and select Developer if you aren’t already in that perspective.
2. In the navigation menu, click +Add (Figure 3).

3. Click the Project drop-down menu and select the <username>-dev project that has been created for you.
4. On the +Add page, click the Container Image tile.
5. In the Image name from external registry field, enter:

   quay.io/evanshortiss/rhoam-quarkus-openapi:latest

6. Change the Runtime icon to quarkus (Figure 4).

7. Scroll to the bottom of the page, select Resource type under the Advanced options section. Then choose the Deployment option (Figures 5 and 6).

   

   Figure 5: Select Resource type under Advanced options.
   

   Figure 6: Deployment option has been chosen.
8. At the bottom of the form, click Create (Figure 7). 

9. This procedure will deploy the application and show the Topology view. The application is represented by a light gray area with a white border. The deployment is a white circle (Figure 8).

10. Click the Open URL arrow icon on the deployment.
11. This opens a new browser window that displays the Quarkus application homepage (Figure 9).

12. Append /q/openapi?format=json to the URL in the address bar to confirm that you can access the OpenAPI Spec for the application (Figure 10). Ensure that the URL is http and not https.

If you see the JSON, you have successfully deployed this application on OpenShift.

Annotate the application for Service Discovery

At this point of this tutorial, we have:

• Set up an OpenShift API Management Tenant on the OpenShift sandbox
• Deployed a Quarkus application on OpenShift and annotated it for Service Discovery

In this section, we will add metadata to the previously deployed Quarkus application to make it easily discoverable by OpenShift API Management. 

Service Discovery is a feature of Red Hat 3scale API Management that helps you import services from an OpenShift cluster. The 3scale API Management instance provided by OpenShift API Management has the Service Discovery feature enabled and preconfigured.

When Service Discovery is configured, 3scale API Management scans for discoverable API services that are running in the same OpenShift cluster and automatically imports the associated API definitions into 3scale. Additionally, 3scale API Management can update the API integration and its specification, based on the  OpenAPI Specification (OAS), to resynchronize them with the cluster.

Here is how to add the annotations and a label to make your Quarkus application available for Service Discovery:

1. Navigate to the Topology view.
2. Click the Quarkus deployment that you created in the previous section. A panel will appear on the right (Figure 11).

3. Select the Resources tab in the panel.
4. Click the rhoam-quarkus-openapi link under the Services heading to load the Service details screen (Figure 12).

5. Use the Edit link beside the Labels heading to add a label with the key discovery.3scale.net and value true (Figure 13).

6. Scroll down and click Annotations to open the Edit annotations dialog for the Service.
7. Use the Add more button to add the following key-value pairs (Figure 14):
   • Key discovery.3scale.net/description-path, value /q/openapi?format=json
   • Key discovery.3scale.net/port, value 8080.
   • Key discovery.3scale.net/scheme, value http.

8. Click the Save button after you've added the three annotations.

Import the API into 3scale API Management

At this point of this tutorial, we have:

• Set up an OpenShift API Management Tenant on the OpenShift sandbox.
• Deployed a Quarkus application on OpenShift and annotated it for Service Discovery.

In this section, we will:

• Launch the API Management Dashboard.
• Import the API into 3scale API Management using Service Discovery.

Access the API Management Dashboard

1. In the OpenShift console, select Project from the left-side navigation pane.

2. Click the <username>-dev project to pull up its web page (Figure 15).

3. In the Launcher pane on the right side, select API Management, which will open OpenShiftbAPI Management in a new tab.
4. Choose to authenticate using Red Hat’s single sign-on technology, and log in using the identity provider that applies to you, e.g., DevSandbox.
5. A welcome message is displayed if this is your first time logging into 3scale API Management. Dismiss the dialog box or read through the welcome message pages. You are now at the Red Hat 3scale API Management dashboard (Figure 16).

 

Import the API

Now let’s go ahead and configure the API. Your API in OpenShift API Management is referred to as a product. Products can have one or many backends. A backend is a web service that OpenShift API Management proxies requests to, based on mapping rules defined by the product. Your Quarkus application is a backend that will be part of your API product.

Because you already configured the Quarkus API for Service Discovery in an earlier section, you can import it automatically as follows:

1. Click the Create Product button under the APIs heading on the dashboard. This will load the New Product screen.
2. Select the Import from OpenShift option. If this option is grayed out, click the (Authenticate to enable this option) link to enable it.
3. After selecting the Import from OpenShift option, you will be able to use the drop-down fields (Figure 17) to select:
   • The namespace that contains your Quarkus application.
   • The rhoam-quarkus-api application.

4. Click the Create Product button.

You will be redirected back to the 3scale API Management dashboard, which will show your new API (Figure 18). If your Quarkus API isn’t listed in the APIs section after a few moments, try refreshing the page.

Verify the API product and backend

You can inspect the product and backend as follows:

1. Select the rhoam-quarkus-openapi API from the Products list to visit the Overview screen.
2. Click the ActiveDocs link on the left and verify that the rhoam-quarkus-openapi Swagger 3.0 spec was imported (Figure 19).

3. Expand the drop-down menu in the top navigation bar and select Backends (Figure 20).

4. Verify that your rhoam-quarkus-openapi backend is listed. You should also see that it's using a private service URL, such as http://rhoam-quarkus-openapi.user-dev.svc.cluster.local:8080. 3scale API Management will proxy incoming requests to this private service URL. (Figure 21)

Enable API Key security

At this point of this tutorial, we have:

• Set up an OpenShift API Management Tenant on the OpenShift sandbox.
• Deployed a Quarkus application on OpenShift, and annotated it for Service Discovery.
• Launched the 3scale API Management dashboard, and created a product and a backend by automatically importing the Quarkus service.

In this section, we will:

• Create an API Key for the Quarkus HTTP API service to restrict access.
• Secure and manage the HTTP API using Red Hat OpenShift API Management.

OpenShift API Management routes API requests through proxies known as APIcast instances. APIcast is an NGINX-based API gateway that integrates your internal and external API services with the Red Hat OpenShift API Management Platform. APIcast enforces API security rules and policies. It supports multiple authentication patterns, and API Key security is the default setting for imported APIs. 

Since your API is now imported into OpenShift API Management, you'll need an API Key to make authenticated requests against it.

Obtain the APIcast URL for the API

1. In the 3scale API Management dashboard, select rhoam-quarkus-openapi from the Products list (Figure 22).

2. Navigate to Integration→Configuration using the side menu. Your API is already available via the Staging APIcast, but the user_key parameter in the Example curl for testing field is set to a placeholder (Figure 23).

3. Copy the URL, e.g., https://user-dev-rhoam-quarkus-openapi-3scale-api.cluster.com/?user_key+USER_KEY, and visit it in a browser or call it using your preferred HTTP client.
4. You should receive an Authentication failed response, since the API Key (user_key) placeholder value is not valid.

To obtain an API Key, you need to create an application plan and subscribe your application to that plan.

Create an application plan

In OpenShift API Management, application plans define usage rules and limits for your API. When a developer signs up to use your API, they can select an application plan from the ones you’ve defined. For example, you might create two application plans with different limits and pricing structures for an API, e.g., one free and the other paid.

Let’s create an application plan for the product that we have already created:

1. Select rhoam-quarkus-openapi from the Products list.
2. Navigate to Applications→Application plans using the side menu.
3. Click the Create Application Plan button.
4. Enter the following values (Figure 24):
   • RHOAM Open API Plan for Name.
   • rhoam-openapi-plan for the System name.
   • Uncheck the Applications require approval box.

5. Click Create Application Plan. You will be redirected to the Application Plans listing.
6. Use the Publish link shown within the kebab menu of the newly created application plan to publish it (Figure 25). The state of this plan will then turn to published.

Configure a developer account to use the application

Now that you’ve created an application plan, you’ll need to sign up for a developer account (named Audience in this example) to use the application. 

Typically, an API consumer signs up using your 3scale API Management developer portal, and a developer account is created for them during signup. For the purpose of this lab, you will manually provide the default developer account with API access. You can create accounts using the dashboard or API.

For the developer account, you will then add an application that is a subscription to the service (API Product) through the application plan created in the previous step. An application is linked to developer accounts for each application plan they sign up for. The application is normally associated with a unique set of credentials for the API, a traffic history of the calls sent to the API, and metadata captured at application creation.

Let’s go ahead and create the Audience developer and associate an Application to it:

1. Expand the drop-down menu in the top navigation of OpenShift API Management and select Audience. 
2. Choose the Developer account from the Account listing (Figure 26). You can choose to create a new Audience as well.

3. From the Developer account page, select the Applications link at the top (Figure 27).

4. Click the Create Application button (Figure 28).

5. Use the following details to create the application (Figure 29):
   1. Select rhoam-quarkus-openapi for the Product, and select RHOAM Open API Plan for the Application Plan.
   2. Enter Developer RHOAM Application in the Name and Description fields.

6. Click the Create Application button. You'll be redirected to the Developer RHOAM Application page, and should see a User Key listed under the API Credentials section (Figure 30). Copy this key to use when sending requests to the application.

Call the API using your API Key

Now that you have a valid API Key, your Audience developer is ready to make authenticated requests against your API:

1. Select rhoam-quarkus-openapi from the Products list on the OpenShift API Management dashboard. An Overview page is displayed (Figure 31).

2. Navigate to Integration→Configuration using the side menu.
3. Copy the staging URL, e.g., https://user-dev-rhoam-quarkus-openapi-3scale-api.cluster/?user_key=<API_KEY_GOES_HERE (Figure 32),  and visit it in a browser or using your preferred HTTP client. Make sure to replace the API Key value with your developer’s key.

4. Append /fruits to the path, but before the ?user_key portion of the URL. A list of fruits should be returned in JSON format (Figure 33).

5. You can also very easily view the usage of this application: 
   1. Simulate multiple hits by accessing this URL multiple times through a browser. 
   2. In the Audience dashboard, click the Developer account.
   3. Click Applications→Listing→Developer RHOAM Application.
   4. You will be able to view the Usage in last 30 Days (Figure 34).

Delete the unprotected route

You visited a URL exposed directly by a route in your OpenShift project in the first section of this guide. This endpoint was useful for testing but is unprotected. You can remove this public route now that your API is protected using an API Key:

1. In the OpenShift console where the Quarkus API is deployed, click the rhoam-quarkus-openapi deployment in the Topology view.
2. Select Resources tab in the panel that appears (Figure 35).

3. Click the (RT)rhoam-quarkus-openapi item under the Routes heading (Figure 36).

4. Expand the Actions drop-down and click Delete Route.

Congratulations! The only endpoint available to access your API now enforces API Key security. You can validate that the API is still accessible through the staging URL shown in Figure 30. 

What just happened?

You have achieved quite a bit with this tutorial. Here is a quick overview of the procedure we went through:

• Set up a sandbox environment and an OpenShift API Management tenant.
• Deployed a Quarkus container image and configured it to be easily discoverable by API Management.
• Created a product and backend for the Quarkus HTTP API.
• Created an application plan for the product.
• Associated this application plan to a developer, which generated an API Key to secure API access.
• Viewed the usage of the application in terms of the number of hits to the API.
• Tested API access using the API Key.
• Deleted the public route to ensure that the API cannot be accessed via that method.