RedHat 3Scale API Management Tutorial: Part-1 Develop the first API

3scale is a powerful API management platform from RedHat. It helps secure the APIs, manages the API life cycle, productizes the APIs, enables us to share the API products with the consumers, and has the API monetization feature. It ticks all the primary requirements of a full-fledged API management platform. In this RedHat 3Scale API Management Tutorial, we’ll start from scratch and learn to develop the first API.

Use Case of the POC

We intend to build a straightforward POC. Here are the basic steps:

• We will mock a REST API implementation using https://mockable.io for this proof of concept. We’ll consider this as the backend API.
• We’ll configure 3scale to expose this backend API.
• We’ll publish the API and observe it in the API developer portal.
• We’ll register as consumers in the API developer portal, create an application, and subscribe to the API plan.
• We’ll test the API.

Prerequisite

Setup RedHat 3Scale API Management Environment

We can deploy the RedHat 3Scale API Management platform on-premise or in the cloud, or we can also use the managed SaaS service solution by RedHat. 3Scale API management also supports hybrid-cloud architecture.

Of all these options, the easiest way to explore the RedHat 3Scale API Management Platform is to create a trial account in its hosted environment. Let’s explore:

• Head to https://www.3scale.net/
• Click on the Start Free Trial link in the top right corner. A signup page will open up.

• Fill up the form with your valid email and other detail. You can refer to mine below. Once you click the Signup button, it’ll take you to the next page and send an activation email to the email you mentioned.
• Please note down the URLs of both the developer-portal and api-admin-portal from this page.

• Click on the link in the email and activate your account in the 3scale platform. Please note that this is a trial account and is valid for 90 days unless you upgrade.
• Once you activate your account and complete the onboarding wizard, you will see the admin portal home page below.

• At this point, we are all set to start configuring our first API.

At this point, If we invoke the endpoint, we will see the response. So, our mock backend API is ready!

Development/Configuration in RedHat 3Scale API management

Now, log in to the admin portal. Ensure that you are in the Dashboard perspective (yellow highlighted menu below).

In 3Scale API development, we work with two broad categories or groups:

• Backend: This is the backend-facing object representing the API we plan to expose through 3Scale.
• Product: This customer-facing abstraction wraps one or more backends ( APIs) under the hood.

Create a new Backend

In this section, we will configure our backend API implementation (i.e., the mock we created above) :

• Click on the Create Backend button; fill the form on the next page like below. Describe this backend by filling in the name, system name, description, and private base URL.
• In the Name field, we’ll fill in Orders Management System.
• The System name is an identifier used by 3scale for its internal processing. Provide a name of your choice by following the below rules:
  • It must be unique in the Product or the Backend configurations.
  • You can use underscores, hyphens, or forward slashes in the system name field, and there must not be any space in between
  • In this POC, we’ll use order_management_system_backend.
• We use the Description field to describe the backend. In this POC, we will describe the backend as the Backend configuration of the Order Management System.
• In the Private Base URL field, provide the shared portion of the URL that all the backend operations will reuse. In the current POC, I provided just the backend host name and its protocol.
• Click on the Create Backend button.

Create Backend Methods and Metrics

• Click on “Methods and Metrics” from the menu on the left side. A page will open with two tabs representing Methods and Metrics.
• If you click on the Metrics tab, you will notice a metric with the name Hits is already present. This is the 3Scale native metric.
• Click on the Methods tab and then on the Add a method button. A new page will open up with a form. Fill it as below:
  • Friendly Name: Create Order
  • System Name: create_order_backend
  • Description: This backend method is for creating an order
• We’ll create another method for fetching order details. So, click on the Add a method button again. A new page will open up with a form. Fill it as below:
  • Friendly Name: Get Order By Order Number
  • System Name: get_order_by_order_number_backend
  • Description: This backend method is for getting the order detail by order number
• After creating both methods, it will look like the below:

Create Backend Mapping Rules

The purpose of the mapping rule is to capture the usage data of the methods/metrics we create as part of the Product or Backend configurations.

Here, we’ll create two mapping rules. We’ll associate each mapping rule with one of the relevant Methods developed above.

• Click on the Mapping Rules from the menu on the left side. A new page will open up. We’ll create the first mapping rule for the createOrder operation:
• Click on the Create mapping rule button. A new page will open up with a form. Fill it up like below:
  • Verb: POST
  • Pattern: /api/v1/order. This is the URI of our backend API to create orders.
  • Ensure the Method option button is selected in the Method or metric to increment section. Click on the drop-down and select Create Order from the list.
  • Increment by: This field is pre-populated with 1. Keep it as it is.
  • Last: Keep the checkbox on the right of Last unchecked. This is to signify that this is NOT the final mapping rule.
  • Position: This is the position of the mapping rule in the list for this backend. In our case, it is the first rule. So, keep the position value as 1.
• Once done, the form will look as follows: CHANGE THE PIC BELOW

• Next, we’ll create the second mapping rule for the getOrderByNumber operation.
• Click on the Create mapping rule button once again. A new page will open up with a form. Fill it up like below:
  • Verb: GET
  • Pattern: /api/v1/order/{orderNumber}. This is the URI of our backend API to get an order by the order number. Consumes will pass the order number in the curly brace {} representing the path parameter.
  • Ensure the Method option button is selected in the Method or metric to increment section. Click on the drop-down and choose Get Order By Order Number from the list.
  • Keep the Incremement by field set to 1.
  • Last: Keep the checkbox on the right of Last checked. This is to signify that this is the last mapping rule.
  • Position: This is the position of the mapping rule in the list for this backend. In our case, it is the second rule. So, keep the position value as 2.
• Once done, the list of mapping rules will look as follows:

Create a new Product

Now, we will create a Product to be exposed to the consumers.

• Go to the Dashboard by clicking on the Dashboard from the top-left corner drop-down menu.
• Click on the Create Product button to create an Order Management Product.

Please note that in my case, I am using trial version of 3scale hosted solution. It doesn’t allow me to create a new product. So, I will edit the existing product (that it supplies with the trial version) to update its Name and Description. I’ll also delete the Backend, ActiveDocs, Mapping Rules configuration, etc. that came by default and reconfigured with the relevant details of the current POC.

Create Product Methods and Metrics

• Click on the newly created/updated Product to open the product configuration page. Click on the Methods and Metrics sub-menu item under Integration.
• First, we will create Create Order method with the following configuration:
  • Friendly Name: Create Order
  • System Name: create_order
  • Description: Create Order method
• Next, we will create the Get Order By Order Number method with the following configuration:
  • Friendly Name: Get Order By Order Number
  • System Name: get_order_by_order_number
  • Description: Get Order By Order Number method
• After creating these methods, we will see something like the below:

Create Product Mapping Rule

Just to remind ourselves, we configure the mapping rules to capture the usage data of the methods/metrics we create as part of the Product or Backend configurations.

Here, we’ll create two mapping rules. We’ll associate each mapping rule with one of the Methods we created above.

• Click on the Mapping Rules from the menu on the left side. A new page will open up.

• Click on the Create mapping rule button. A new page will open up with a form. We’ll create the first mapping rule for the createOrder operation:
  • Verb: POST
  • Pattern: /app/rest/api/v1/order. If you notice, we have prefixed /app/rest before the actual backend URI.
  • Ensure the Method option button is selected in the Method or metric to increment section. Click on the drop-down and select Create Order from the list.
  • Increment by: This field is pre-populated with 1. Keep it as it is.
  • Last: Keep the checkbox on the right of Last unchecked. This is to signify that this is NOT the last mapping rule.
  • Position: This is the position of the mapping rule in the list for this Product. In our case, we want to keep this rule as the first rule. So, keep the position value as 1.
  • Click on the Create mapping rule button.
• Next, we’ll create the second mapping rule for the getOrderByNumber operation.
• Click on the Create mapping rule button once again. A new page will open up with a form. Fill it up like below:
  • Verb: GET
  • Pattern: /app/rest/api/v1/orders/{orderNumber}. Aside from the prefix /app/rest, the rest of the URI is of our backend API to get an order by the order number. The consumer will pass the order number in the curly brace {} that signifies the path parameter.
  • Ensure the Method option button is selected in the Method or metric to increment section. Click on the drop-down and choose Get Order By Order Number from the list.
  • Keep the Incremement by field set to 1.
  • Last: Keep the checkbox on the right of Last checked. This is to signify that this is the last mapping rule.
  • Position: This is the position of the mapping rule in the list for this Product. In our case, it is the second rule. So, keep the position value as 2.
• Once done, the list of mapping rules will look as follows:

Configure Backend

In this section, we’ll associate the backend we created earlier with the Product.

• Ensure that you are still on the Product configuration page.
• Click on the Backends submenu item under Integration.
• Click the Add backend button; a new page with a form will open up.
• Click on the drop-down list and choose the backend we created initially. In our case, the Backend is Order Management System.
• In the Path field, write /app/rest. This will be the base path for the published APIs.

• Click on the Add to product button. You’ll see a page like the one below:

Configure Settings

Click on the Settings submenu item under Integration. Here we’ll configure quite a few things. Follow the below steps:

DEPLOYMENT

• Under the DEPLOYMENT section, we’ll keep the APICast 3scale managed option checked.
• However, if you are working with self-managed installation, choose the APICast self-managed option and update the appropriate base URL

AUTHENTICATION

• In the AUTHENTICATION section, there are three options. For this POC, I’ll select the second option, App_ID and App_Key Pair. The application is identified via the App_ID and authenticated via the App_Key option.
• We’ll keep the App ID and App Key parameter name ASIS.
• In the CREDENTIAL LOCATION sub-section, choose the credential location as the HTTP header.
• Click on the Update Product button.

We’ll keep the rest of the settings AS-IS without any changes.

Create API Plans

Plans establish various usage rules of the API—for example, rate limit or throttling policy, pricing rules, features, etc. A developer’s application subscribes to a plan and complies with the rules set by that specific plan. We create plans keeping our target audience and their possible user requirements.

For our POC, we want to create two plans as follows:

• Silver Plan:
  • It’ll contain only Create Order API
  • We’ll specify the usage limit to 1 request per minute.
  • Admin needs to approve the subscription request by developers.
• Gold Plan:
  • It will contain both Create Order and Get Order API
  • We’ll specify the usage limit to 2 requests per minute.
  • Admin needs to approve the subscription request by developers.

Let’s configure these plans:

• Click on the Application Plans submenu of the Application menu item.
• You’ll notice that there are already two plans, Basic and Unlimited. Hide these plans by clicking on the vertical ellipsis or kebab menu on the extreme right.
• Click the Create application plan button in the top right corner to create our first plan.
• A new page will open up with a form. Fill it up as follows:
  • Name: Silver Plan
  • System name: silver_plan
  • Applications require approval?: Tick the checkbox.
  • Click on the Create application plan button.
• Click the Create application plan button in the top right corner to create our second plan.
  • Name: Gold Plan
  • System name: gold_plan
  • Applications require approval?: Tick the checkbox.
  • Click on the Create application plan button.
• Now click on the Silver Plan to configure it with the usage rules that we defined above:
  • Under the Metrics, Methods & Limits section, locate the Get Order By Order Number method.
  • Click on the green tick sign under the Enabled column to disable it.
  • A limit with 0 call/eternity will automatically be created. Keep it AS-IS.
  • Now, locate the Create Order method. Click on the limit (0).
  • After that, click on the New usage limit link to create a limit of 1 call/minute.
  • Scroll down to the Features section.
  • Configure the features as shown in the below snippet.
  • Click on the Update Application plan button.

• Now click on the Gold Plan to configure it with the usage rules that we defined above:
  • Under the Metrics, Methods & Limits section, we’ll keep everything green/enabled for both operations.
  • Now, locate the Create Order method. Click on the limit (0).
  • After that, click on the New usage limit link to create a limit of 2 calls/minute.
  • Locate the Get Order By Order Number method. Click on the limit (0).
  • After that, click on the New usage limit link to create a limit of 2 calls/minute.
  • Scroll down to the Features section and create/edit features as shown in the below snippet.
  • Click on the Update Application plan button.

• From the Application Plans list, change the default plan to Silver Plan.

Configure ActiveDocs

We have done many configurations so far. However, it does not automatically create any consumer-friendly API document like swagger. To make a swagger API document available to the user in the developer portal, we need to configure the ActiveDocs section separately with the swagger content. Let’s see how we can do it:

• Click on the ActiveDocs menu item while still on the Product configuration page. A new page will open up.
• On the right of the page, click on Create your first spec link.
• A new page will open up with a form. Fill it up like below:
  • Name: Order Management API Documentation
  • System Name: OrderManagementAPIDcoumentation
  • Click on the checkbox on whether to Publish? field and ensure it is checked.
  • Description: This API provides the authenticated consumers the ability to create an order and also fetch the order details provided the consumer has a valid order number
  • API JSON Spec: Paste the swagger definition of the API we plan to publish. I have provided the complete swagger below. You can just copy/paste in the designated field.
• Click on the Create Spec button.
• This will create specifications of our API and publish them to the developer portal. We’ll go to the developer portal configuration in a bit.
• After successfully configuring it, we can click on the ActiveDocs menu item again and preview the swagger documentation.

Configure Developer Portal

Before making any changes, let’s first visit the developer portal.

• Click on the Audience menu item from the top-left corner drop-down menu.
• Click on the Developer Portal -> Visit Portal.
• It’ll open the developer portal in the new tab. It’ll look like below:

• The portal is highly customizable and can be suited to the organization’s needs. However, we’ll make a simple modification in the portal to replace the Echo API title with Order management API.
• While still in the Audience perspective, click on Developer portal -> Content.
• Click on the Homepage submenu on the newly opened page on the right pane. Replace the Echo API with the Order Management API in the Draft section.

• Click on the Save button and then on Publish button at the bottom of the page.
• Now, if you click on the Developer Portal -> Visit Portal, the updated page will be visible:

Publish the API Configuration to API Gateway

• Click on the Product menu item from the top-left corner drop-down list.
• Click on Integration -> Configuration and then click on Promote v.1 to Staging APIcast button. This will publish the API configurations in the API Gateway.

Publish the API plans

• While still on the Product configuration page, click on Applications -> Applications Plans.
• Click on the vertical ellipsis or kebab menu on the extreme right of the Gold Plan and Silver Plan and publish both plans.

Revisit the Developer Portal

• Click on the Audience menu item from the top-left corner drop-down menu.
• Click on the Developer Portal -> Visit Portal.
• It’ll open the developer portal in the new tab. The home page will look like the below:

• Now clicking on the DOCUMENTATION menu item will render a page the like below:

Consumer onboarding journey

Register as a consumer in RedHat 3scale API developer portal

• Go back to the developer portal. Click on the SIGN IN link in the top right corner. A page will open up for signing in. As we want to create a new user, click on the Signup hyperlink to navigate to the user registration page.
• Fill in the form (use a valid email) and click the Signup button. You’ll see a page like the one below:

• Now go to the email box you used above to signup as a consumer. There’ll be an email with a link. Click on the link to activate and complete your registration.
• Now, sign in again with the credential you used during registration.
• After signing in, click on the API CREDENTIAL menu item. You’ll see a screen similar to the one below:

• Let’s observe a few essential points:
  • Our application is auto-subscribed to Silver Plan. This is because we previously set this particular plan as the default one.
  • The application is pending approval.
  • Not down the application-id and application key. We’ll use this for testing later.

Approve the application from RedHat 3scale API Management admin portal

• Let’s approve the application. To do this, go back to our 3scale administration portal. Ensure that you are on the product configuration page.
• Click on Applications -> Listing. This will open and render the list of applications.

• Click on the app and Approve button.

• Once approved, you will receive an email in the email id used during the registration process.
• Now, we are good to test.

Test the API

• We’ll use the cURL utility to test the APIs. Replace the app_id, app_key, and hostname with the actual values of your test environment.

• If you keep hitting the API, you will notice that the moment you exceed the defined limit, you will have the following error:

Analytics in the Provider’s Organization

• Ensure to be on the Product configuration page and navigate to Analytics -> Traffic to observe the traffic analytics like the below:

Analytics in the Consumer Organization

• Visit and sign in to the developer portal.
• Click on the STATISTICS menu from the top, and you’ll see the API usage analytics for the signed-in consumer:

Share this RedHat 3Scale API management tutorial in your network if you found it informative and it helped you in any way!!