Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

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

February 23, 2021
Evan Shortiss
Related topics:
JavaKubernetesQuarkus
Related products:
Red Hat OpenShift API Management

Share:

    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:
      • Git CLI
      • Java 8 or 11+
      • Maven 3.6.2
      • OpenShift CLI 4.5 or later

    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

    Recent Posts

    • Storage considerations for OpenShift Virtualization

    • Upgrade from OpenShift Service Mesh 2.6 to 3.0 with Kiali

    • EE Builder with Ansible Automation Platform on OpenShift

    • How to debug confidential containers securely

    • Announcing self-service access to Red Hat Enterprise Linux for Business Developers

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit
    © 2025 Red Hat

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue