Article

5 steps to manage your first API using Red Hat OpenShift API Management

February 23, 2021
JavaKubernetesQuarkus
Evan Shortiss
Guest Author
Featured image: 5 step API management.

Companies are increasingly using hosted and managed services to deliver on application modernization efforts and reduce the burden of managing cloud infrastructure. The recent release of Red Hat OpenShift API Management makes it easier than ever to get your own dedicated instance of Red Hat 3scale API Management running on Red Hat OpenShift Dedicated.

This article is for developers who want to learn how to use Red Hat's hosted and managed services to automatically import and manage exposed APIs. We'll deploy a Quarkus application on OpenShift Dedicated, then use OpenShift API Management to add API key security. See the end of the article for a video demonstration of the workflow described.

Prerequisites

This article assumes that you already have the following:

  • Access to a cloud.redhat.com account.
  • An existing OpenShift Dedicated cluster or the ability to deploy one.
  • Entitlements to deploy the Red Hat OpenShift API Management add-on.
  • A development environment with:

Step 1: Obtain an OpenShift Dedicated cluster

Using a hosted and managed service like OpenShift API Management makes this step straightforward. See this video guide to obtaining an OpenShift Dedicated cluster and installing the OpenShift API Management add-on. You can also find instructions in this article and in the OpenShift API Management documentation.

Once you've obtained your OpenShift Dedicated cluster and installed the Red Hat OpenShift API Management add-on, we can move on to the next step.

Step 2: Create a project using the OpenShift CLI

Logging into an OpenShift Dedicated cluster via the OpenShift command-line interface requires a login token and URL. You can obtain both of these by logging into the OpenShift console via a web browser and using the configured IdP. Click Copy Login Command in the dropdown menu displayed under your username in the top-right corner. Alternatively, navigate directly to https://oauth-openshift.$CLUSTER_HOSTNAME/oauth/token/request and use your web browser to obtain a valid login command.

Once you have a token, issue a login command, then create a new project:

  1. $ oc login --token=$TOKEN --server=$URL
  2. $ oc new-project my-quarkus-api

Step 3: Deploy the Quarkus application to OpenShift

The Java application you’ll deploy for this demonstration is based on the example from the Quarkus OpenAPI and Swagger UI Guide. It’s a straightforward CRUD application that supports using a REST API to modify an in-memory list of fruits. You'll find the source code in this GitHub repository.

Our application's codebase differs slightly from the Quarkus OpenAPI and Swagger UI Guide example. I made the following changes:

  1. Set quarkus.smallrye-openapi.store-schema-directory in application.properties.
  2. Updated .gitignore to openapi.json and openapi.yaml.
  3. Added the quarkus-openshift extension.

These modifications create a local copy of the OpenAPI spec in JSON format and include tooling that simplifies the deployment process.

Build and deploy the Quarkus application

Start by cloning the repository to your local environment:

$ git clone https://github.com/evanshortiss/rhoam-quarkus-openapi

Issue the following command to start a local development server and view the Swagger UI at http://localhost:8080/swagger-ui:

$ ./mvnw quarkus:dev

Enter this command to build and deploy the application on your OpenShift Dedicated cluster:

$ ./mvnw clean package -Dquarkus.kubernetes.deploy=true -Dquarkus.openshift.expose=true

The build progress will be streamed from the OpenShift build pod to your terminal. You can also track the build logs and status in the project's Builds section in the OpenShift console, as shown in Figure 1.

Viewing Build logs in the OpenShift Console
Viewing Build logs in the OpenShift Console
Figure 1: Viewing build logs in the OpenShift console.

Once the build and deployment process is complete, the URL to access the application will be printed in your terminal. Use this URL to verify that the application's OpenAPI spec is available at the /openapi?format=json endpoint. It’s important to verify that the JSON response is returned. You'll need it to import the API to 3scale API Management and automatically generate the 3scale API Management ActiveDocs. Figure 2 shows an example of the response returned by this endpoint.

Quarkus Fruits API Spec
Figure 2: Viewing the Open API Specification in JSON Format
Figure 2: Viewing the OpenAPI specification in JSON format.

Step 4: Apply Service Discovery annotations

Next, we'll import the API into 3scale API Management using its Service Discovery feature. For this step, we need to apply a specific set of annotations and labels to the service associated with the Quarkus application. The Service Discovery annotations and labels are documented here.

Use the following commands to apply the necessary annotations:

$ oc annotate svc/rhoam-openapi "discovery.3scale.net/description-path=/openapi?format=json"
$ oc annotate svc/rhoam-openapi discovery.3scale.net/port="8080"
$ oc annotate svc/rhoam-openapi discovery.3scale.net/scheme=http

Add the discovery label using the following command:

$ oc label svc/rhoam-openapi discovery.3scale.net="true"

Verify the label and annotations using:

$ oc get svc/rhoam-openapi -o yaml

The output should be similar to the sample displayed in Figure 3.

Quarkus Fruits API Service YAML
Figure 3: The Quarkus API Service definition in YAML format with annotations and labels applied.
Figure 3: The Quarkus API Service definition in YAML format with annotations and labels.

Step 5: Use Service Discovery to import the API

At this point, you can import the Quarkus Fruits API and manage it using 3scale API Management's Service Discovery feature. Use the OpenShift Dedicated application launcher to navigate to the 3scale API Management console. Figure 4 shows the application launcher in the top-right corner of the OpenShift Dedicated console.

OpenShift Dedicated Console & Application Launcher
Figure 4: Using the Application Launcher in the OpenShift Dedicated Console to access 3scale API Management
Figure 4: Using the application launcher to access 3scale API Management.

Import the API

Log in to 3scale API Management using your configured IdP, and click the New Product link on the dashboard. Perform the following steps on the New Product screen:

  1. Select Import from OpenShift (authenticate if necessary).
  2. Choose the my-quarkus-api namespace from the Namespace dropdown.
  3. Choose the rhoam-openapi service from the Name dropdown.
  4. Click the Create Product button.

Figure 5 shows the new product screen in 3scale API Management.

3scale New Product Screen
Figure 5: Using the Import from OpenShift option on the New Product screen in 3scale API Management
Figure 5: Creating a new product in 3scale API Management.

At this point, you should be redirected back to the 3scale API Management dashboard. If your new API isn’t listed in the APIs section after a few moments, try refreshing the page. Once the API has been imported and listed on the dashboard, expand it and click the ActiveDoc link. Select rhoam-openapi on the subsequent screen to view the live documentation that was generated from the OpenAPI specification, as shown in Figure 6.

3scale ActiveDocs Page
Figure 6: Viewing the generated ActiveDocs in 3scale API Management
Figure 6: Viewing the generated ActiveDocs in 3scale API Management.

Create an Application Plan in 3scale API Management

Next, you’ll need to configure an Application Plan to interact with the API via a protected route:

  1. Choose Product: rhoam-openapi from the top navigation bar.
  2. Select Applications > Application Plans from the menu on the left.
  3. Click the Create Application Plan link.
  4. Enter “RHOAM Test Plan” in the Name field.
  5. Enter “rhoam-test-plan” in the System name field.
  6. Click the Create Application Plan button.
  7. Click the Publish link when redirected to the Application Plans screen.

Figure 7 shows the dialog to create a new application plan in 3scale API Management.

3scale Create Application Plan Screen
Figure 7: Creating an Application Plan in 3scale API Management
Figure 7: Creating an application plan in 3scale API Management.

Configure a developer account to use the application

Now that you’ve created an Application Plan, you'll need to sign up a developer account to use the application. Typically, an API consumer signs up using your API Developer portal. For the purpose of this demonstration, you will manually provide the default Developer account with API access:

  1. Select Audience from the top navigation bar.
  2. Select the Developer account from the Accounts list.
  3. Click the 1 Applications link from the breadcrumb links at the top of the screen.
  4. Click the Create Application link and you’ll be directed to the New Application screen.
  5. Select RHOAM Test Plan as the Application Plan.
  6. Enter “RHOAM Test Application” in the Name field.
  7. Enter a description of the API.
  8. Click Create Application.

Once the application is created, you’ll see that an API key is listed under the API Credentials section, as shown in Figure 8. Take note of the key.

3scale Application Details Screen
Figure 8: An API Key is generated when an Application is created for a user in 3scale API Management
Figure 8: Creating an application for a user generates an API key.

Test the application

Use the top navigation bar to navigate back to the Quarkus API's product page, then open the Integration > Configuration section. The Staging APIcast section should include an example cURL command for testing, as shown in Figure 9. Copy this command and add /fruits to the URL, e.g https://my-quarkus-api-3scale-staging.$CLUSTER_HOSTNAME:443/fruits?user_key=$YOUR_API_KEY

3scale API Configuration Screen
Figure 9: The example cURL command now contains a valid API Key
Figure 9: The example cURL command now contains a valid API key.

Issuing the cURL command or pasting the URL into a web browser returns the list of fruits from the Quarkus API. Congratulations: You’ve deployed a Quarkus-based REST API on OpenShift and protected it using Red Hat 3scale API Management.

Video demonstration: Red Hat OpenShift API Management

If you want to go over the steps in this article again, see this video guide to using Red Hat OpenShift API Management, Quarkus​, and 3scale API Management to automatically import and manage exposed APIs.

Summary and next steps

If you’ve made it this far, you have successfully:

  • Provisioned an OpenShift Dedicated cluster.
  • Installed the Red Hat OpenShift API Management add-on.
  • Deployed a Quarkus application on your OpenShift Dedicated cluster.
  • Applied custom labels and annotations to a service using the OpenShift CLI.
  • Imported the Quarkus API into 3scale API Management and protected it using API key security.

Now that you’ve learned the basics of OpenShift Dedicated and 3scale API Management, why not explore other OpenShift Dedicated and Red Hat OpenShift API Management features? Here are some ideas:

  • Familiarize yourself with the single sign-on instance that’s included with your Red Hat OpenShift API Management add-on. You could consider using Red Hat's single sign-on (SSO) technology instead of API key security to protect routes using OpenID Connect. (SSO is accessible from the OpenShift Dedicated application launcher.)
  • Learn more about OpenShift and your cluster by following a quickstart from the OpenShift web console's developer perspective.
  • Delete the unprotected route to the Quarkus API using the OpenShift console or CLI. This was the route you used to view the OpenAPI in JSON format.

Happy coding!

Last updated: January 20, 2023