Chapter 1. First steps with 3scale

This guide is an introduction to the features you can find in Red Hat 3scale API Management. You will learn how to integrate and manage your API, both from customer-facing and internal perspectives. For more information, you will also find links to resources from each section.

1.1. Products and backends

This section describes how Red Hat 3scale API Management works with APIs. 3scale separates your APIs into two main groups:

  • Backends: Internal APIs bundled in a product. Backends grant API Providers the freedom to map their internal API organization structure to 3scale.
  • Products: Customer-facing APIs. Products facilitate the creation of strong and simplified offerings for API consumers.

A product can contain multiple backends, and a backend can be used in multiple products. In other words, to integrate and manage your API in 3scale you need to create both:

  • A Backend containing at least the URL of your API. The backend can optionally have mapping rules, methods and metrics to facilitate reusability.
  • A Product where you define the application plans, and configure APIcast.

1.2. Configuring your first API using the 3scale wizard

In this section, you will learn about the 3scale wizard, which provides initial help when working with products and backends.

Prerequisites

  • You need a 3scale account.

Procedure

  1. Run the wizard. You can run the 3scale wizard in two ways:

    • The first time you log in to your 3scale account.

    • Running the wizard by replacing [Your_admin_domain] in the following URL address:

      https://[Your-admin-domain]-admin.3scale.net/p/admin/onboarding/wizard/intro

      For example, if your admin domain is testing-area, the wizard is available in:

      https://testing-area-admin.3scale.net/p/admin/onboarding/wizard/intro

  2. Click OK, how does 3scale work?.
  3. Watch the introductory animation. Once done, click Got it! Let’s add my API.

  4. Create a backend:

    1. Specify a name for your backend. For example: Inventory
    2. Indicate a base URL for the backend. Example: https://echo-api.3scale.net:443
    3. Click Add this Backend.

  5. Create a product:

    1. Indicate a product name. For example: Petstore
    2. Click Add this Product.

  6. Indicate a path to connect your backend to your product, and click Add the Backend to the Product.

    • You can leave the default value. Path: /

  7. To make a test with a GET request, click Send request.

    • You can specify a GET method.
  8. After these steps, you will see a confirmation of a successful request to the API Gateway. For more details about the following configurations, click Cool, what’s next?.

Once you have taken a look at the suggested additional configurations, you are ready to use 3scale. Click Got it! Take me to my API on 3scale and you will see the Overview page of your product.

1.3. Initial configurations for your API

This section outlines the initial configurations to ensure that your API traffic is protected by API keys, tracked, and monitored by 3scale with basic rate limits and controls in place. If this is the first time you are working with 3scale, you can run the wizard to get assistance configuring your first API.

1.3.1. Creating new products

A product is a customer-facing API that packages one or more backends. This section describes how to add products to 3scale.

You can create a new product following one of these options:

  • Define the product manually.
  • Import the product from OpenShift.

This section contains details about the manual definition. If you want to import a product from OpenShift, see Service Discovery.

Prerequisites

  • You need a 3scale account.

Procedure

  1. Go to the Dashboard.
  2. Under the APIs section, choose the Products tab.
  3. Click New Product.

  4. Provide the following details:

    • Name: Product identifier.

    • System name: Identifier used for internal purposes. A product system_name is used to generate proxy endpoints and domain names. By default, system_name is part of a label whose pattern can be as one of the alternatives below:

      • For APIcast staging: %{system_name}-%{tenant_name}-apicast-staging

      • For APIcast production: `%{system_name}-%{tenant_name}-apicast-production

        To have OpenShift accept the routes created by Zync, the labels must have a maximum of 63 characters, including the dashes shown in the patterns. Hence, when you specify a system_name, you must consider the limit in the number of characters for the patterns previously described.

    • Description: Optional field containing more details about the product.
  5. Click Create Product.

After these steps, you will have a product that represents the public facing API. The next steps are creating backends and adding them to the product.

1.3.2. Creating new backends

A backend is an internal API that is bundled to a product. This section describes how to create backends and add them to products.

Prerequisites

  • You need a 3scale account.

Procedure

  1. Go to the Dashboard.
  2. Under the APIs section, choose the Backends tab.
  3. Click New Backend.

  4. Provide the following details:

    • Name: Backend identifier.
    • System name: Identifier used for internal purposes.
    • Description: Optional field containing more details about the backend.
    • Private endpoint: Base URL of the private API.
  5. Click Create Backend.

After these steps, you will have an internal API. You can add more backends as needed. The next step is to add this backend to a product.

1.3.3. Adding backends to a product

In this section, you will learn to add a backend to a product. You can repeat this procedure for each backend you want to add to a product.

Prerequisites

Procedure

  1. From [Your_product_name] in the Dashboard, go to Integration > Backends.
  2. Click Add Backend.
  3. From the drop down list, select an existing backend.
  4. Specify the routing path in the Path textbox. For more details, see The backend path.
  5. Click Add to Product.

After these steps, your product will have a backend. You can follow this procedure again in case you want to add more backends to a product, or add a backend to different products.

The backend path

When you add a backend to a product, you define the path the backend uses within the context of this specific product. This path is not part of the backend.

From the procedure described in adding backends to a product, APIcast uses the path of the backend you indicated in step 4. APIcast redirects the traffic to the backend with the specified path matching the prefix of the requested endpoint path.

When defining the path for a backend:

  • You can indicate / as path of one of the backends.
  • Paths must be unique inside the product. This means that you cannot add two backends with the same path inside the same product. Neither you can add the same backend twice to the same product.
  • You can give the same backend the same path in different products.

This is how the backend path works:

  • Each backend added to a product is mounted in the specified path.
  • Before redirecting the traffic, the path is removed from the public URL of the request to the product.

Example

Consider this configuration to add a backend to a product:

  • Backend: Inventory
  • Resource path: /list
  • Product: Petstore
  • Backend path: /supplies

These are the URLs used by your configuration:

  • Public URL: <public-api-domain>/supplies/list
  • Private URL: <private-api-domain>/list

This is the action flow when a request is sent:

  1. The application sends a request.
  2. The request is sent to the public URL: <public-api-domain>/supplies/list
  3. The backend path is removed before redirecting to the private URL: <private-api-domain>/list
  4. The request is redirected to the Inventory backend.

1.3.4. Defining mapping rules

This section describes the definition of mapping rules at the backend level. You can define mapping rules at the backend and product levels. The advantage of defining mapping rules at the backend level is that you will be creating reusable backends that can be added to any product. If you want to learn more about the metrics or methods that you want to report depending on the requests to your API, both at the product and backend levels, see Mapping rules.

Prerequisites

Procedure

  1. From the Dashboard, choose the Backends tab.
  2. Click on the name of the backend you want to configure. For example, API Backend.
  3. In the page containing information about the backend, navigate to Mapping Rules.
  4. Click Add Mapping Rule.

  5. Specify the following settings:

    • Verb: The HTTP request verb (GET, POST, DELETE, or PUT).
    • Pattern: The pattern to match. For example, /hello.
    • Metric or method to increment: The metric or method name.
    • Increment by: The metric increment number. For example, 1.
    • Last?: If this mapping rule should be considered as the last one, to stop processing other mapping rules.
    • Position: Number that indicates the position of the execution of the mapping rule, to sort the mapping rules.
  6. Click Create Mapping Rule.

After these steps, the mapping rule is added to the backend. The mapping rule is also available for each product currently using the backend. To have the mapping rule active at the product level, promote the latest proxy configuration in the product Integration page.

When you promote the latest proxy configuration, 3scale activates at the product level the mapping rules configured in the backend. The mapping rules follow the backend path specified in the product. For example, if you have this configuration:

  • Pattern of the mapping rule at the backend: /thousands
  • Backend is added to a product with path: /unitprice

The final mapping rule at the product level is: /unitprice/thousands

1.3.5. Creating application plans

This section describes how to create a basic application plan for your API. Application plans define the rules such as limits, pricing and features for using your API at the product level. For more information, refer to Application plans and Defining your API (methods and metrics).

Prerequisites

Procedure

To create a new application plan for testing purposes, follow these steps:

  1. Navigate to [Your_product_name] > Applications > Application Plans.
  2. Click Create Application Plan.

  3. On the Create Application Plan page, enter a name and a system name for your new plan.

    • System names must be unique.
  4. Click Create Application Plan.

1.3.6. Creating applications

This section outlines the steps to create a basic application for the default Developer account.

An application subscribes to the application plan. An application is always associated to an application plan. Applications are stored within developer accounts. In basic 3scale plans only a single application is allowed; but, in enterprise plans, multiple applications per account are allowed.

Prerequisites

Procedure

  1. Navigate to Dashboard > Audience > Account.
  2. Click on the default account called Developer.
  3. Go to the Application tab.
  4. Click Create Application.
  5. Choose an application plan.
  6. Specify a name and a description.
  7. Click Create Application.

1.3.7. Testing backends with a product

This section explains how backends are connected to a product, and how you can see the connections. Testing the backends with a product involves promoting the APIcast configuration, to staging and production environments, in order to make tests based on request calls.

Requests to a product are redirected to the corresponding backend according to the path. This path is configured when you add the backend to the product. For example, if you have two backends added to a product, each backend has its own path.

Prerequisites

Procedure

  1. Promote an APIcast configuration to Staging, by navigating to [Your_product_name] > Integration > Configuration.

  2. Under APIcast Configuration, you will see the mapping rules for each backend added to the product. Click Promote v.[n] to Staging APIcast.

    • v.[n] indicates the version number to be promoted.

  3. Once promoted to staging, you can promote to Production. Under Staging APIcast, click Promote v.[n] to Production APIcast.

    • v.[n] indicates the version number to be promoted.

  4. To test requests to your API in the command line, use the command provided in Example curl for testing.

    • The curl command example is based on the first mapping rule in the product.

When testing requests to your API, you can modify the mapping rules by adding methods and metrics.

Every time you modify the configuration and before making calls to your API, make sure you promote to the Staging and Production environments. When there are pending changes to be promoted to the Staging environment, you will see an exclamation mark in the Admin Portal, next to the Integration menu item.

1.3.8. Additional references

For more details about products and backends, you can refer to these articles: