As a new Red Hat OpenShift API Management service user, it is important to understand the typical workflow for creating, securing, and publishing application programming interfaces (APIs). The workflow for using the service comprises a different set of procedures for each type of user:
Administrators manage OpenShift API Management users as well as the API gateway, APIcast, which is the interface that handles calls to an API.
Developers, referred to as 3scale API providers, make APIs accessible by adding them to OpenShift API Management, configuring their use, and publishing them. For new 3scale API providers, there are procedures for getting started.
For all users, a high level understanding of OpenShift API Management components and basic 3scale objects is the foundation for performing the procedures.
Overview of Red Hat OpenShift API Management
Red Hat OpenShift API Management provides you with the ability to create, secure, and publish APIs. The OpenShift API Management service is an add-on to OpenShift Dedicated. The service is based on the Red Hat 3scale API Management platform and also includes an implementation of Red Hat Single Sign-on (SSO). This SSO implementation is for controlling access to 3scale Developer Portals and to 3scale API products. It is not supported as a company-wide SSO solution.
The workflow for using OpenShift API Management starts with an administrator who performs the following tasks:
Configures an identity provider if one has not already been configured
Manages accounts for OpenShift API Management API providers
Adds the OpenShift API Management service to an OpenShift Dedicated cluster
Manages the OpenShift API Management gateway, APIcast, which is the interface that handles calls to an API
3scale API providers are developers who work in the 3scale Admin Portal, for which an administrator has given them accounts. API providers also work in the OpenShift Dedicated cluster to deploy applications, such as a backend for service API requests. API providers create and publish APIs, and can configure Red Hat Single Sign-On authentication to secure APIs. 3scale separates into two main groups:
Backends are internal APIs bundled in a product. Backends grant API providers the freedom to map internal API organization structure to 3scale. A backend contains at least the URL of your API, and can optionally have mapping rules, which define the metrics that indicate the usage of an API. A backend can belong to more than one 3scale product.
Products are customer-facing APIs. Products facilitate the creation of robust yet simplified offerings for API consumers. A product includes application plans and configuration of the APIcast gateway. A product can bundle multiple backends.
When a 3scale product is ready for use, an API provider publishes it in the Developer Portal. API consumers visit the Developer Portal to subscribe to a 3scale product that contains that API. Consumers can then call the API’s operations, subject to any usage policies that may be in effect.
The main OpenShift API Management components include:
APIcast - the 3scale API gateway
Admin Portal - the 3scale console that developers work in
Developer Portal - the interface for API consumers
Red Hat Single Sign-On - for authenticating access to the Developer Portal as well as to APIs
The following image shows how these components work together to provide the service.
Administrator workflow for OpenShift API Management
A Red Hat OpenShift Dedicated cluster administrator sets up the cluster and identity provider and adds the OpenShift API Management service to a cluster. An OpenShift API Management administrator manages service users and the OpenShift API Management gateway, APIcast, which is the interface that handles calls to a 3scale API product.
The workflow comprises multiple procedures that an administrator performs in the order in which they are described here. An introduction to each procedure follows and includes a link to detailed instructions, which are in Red Hat 3scale API Management documentation.
- In the Red Hat OpenShift Cluster Manager console, an OpenShift Dedicated cluster administrator configures an identity provider (unless one is already configured) to authenticate OpenShift API Management users in the cluster.
If an identity provider is already configured, there is no need to configure another one. A cluster administrator chooses and configures an identity provider, which can be LDAP, GitHub, GitHub Enterprise, Google, or OpenID Connect.
Instructions: Configuring identity providers
- In the Red Hat OpenShift Cluster Manager console, an OpenShift Dedicated cluster administrator adds OpenShift API Management to the cluster.
Adding OpenShift API Management to a cluster makes the service available for use by 3scale API providers.
Instructions: Adding OpenShift API Management to your cluster
- In the 3scale Admin Portal, an OpenShift API Management administrator manages 3scale API provider account permissions so API providers can use the 3scale Admin Portal to create, configure, and launch 3scale API products.
Red Hat configures OpenShift API Management to use the cluster’s Single Sign-On instance. This instance is configured to use the OpenShift OAuth server, which is configured to use the identity provider configured by the OpenShift Dedicated cluster administrator.
When a new user logs in to the OpenShift Dedicated cluster by means of the configured identity provider, the user automatically receives an OpenShift account with permission to access OpenShift API Management. An OpenShift API Management administrator manages these accounts in the 3scale Admin Portal.
By default, Single Sign-On is configured for 3scale in OpenShift API Management.
Instructions: Red Hat Single Sign-On for the 3scale Admin Portal
- In the 3scale Admin Portal, an OpenShift API Management configures APIcast policies to control how the API gateway handles requests.
An administrator or an API provider defines APIcast policies. APIcast is the 3scale API gateway, which is the endpoint that accepts API product calls and routes them to bundled backends. OpenShift API Management provides APIcast staging for developing and testing APIs and also APIcast production, for published APIs.
APIcast policies are units of functionality that modify how APIcast operates. Policies can be enabled, disabled, and configured to control APIcast behavior. Use policies to add functionality that is not available in a default APIcast deployment.
Instructions: Administering the API Gateway: APIcast policies
New API provider workflow for OpenShift API Management
OpenShift API Management is based on the Red Hat 3scale API Management platform, which provides many features for developing both customer-facing and internal APIs. A new 3scale API provider gets started by running the 3scale wizard to create, publish and test a sample API.
The workflow comprises multiple procedures that a new API provider performs in the order in which they are described here. An introduction to each procedure follows and includes a link to detailed instructions, which are in Red Hat 3scale API Management documentation.
- In the 3scale Admin Portal, a 3scale API provider runs the 3scale wizard to start learning about how to add and test a 3scale API product.
After signing in to 3scale, the 3scale Admin Portal opens. In the 3scale Admin Portal, an API provider clicks
OK, how does 3scale work?. In the wizard, the API provider creates a backend linked to a product by using a path. A backend is an internal API that is bundled into a product, which is a customer-facing API. In the wizard, the API provider also sends a test request.
Instructions: First steps with 3scale.
- In the 3scale Admin Portal, a 3scale API provider creates API backends, API products, mapping rules and application plans to define a customer-facing API product, capture metrics, and configure API access rules.
An API provider creates and configures an API to ensure that access is protected by API keys, tracked, and monitored by 3scale with basic rate limits and controls in place. Mapping rules define the metrics or methods to report. Application plans define the rules such as limits, pricing and features for using an API product. An application subscribes to an application plan.
Instructions: Initial configurations for your API
- In the 3scale Admin Portal, a 3scale API provider launches a prototype, basic, or advanced API to learn about the requirements for going live and to incrementally customize a published 3scale API product.
An API provider performs a sequence of procedures to launch an API product. The procedures are documented in the 3scale
Getting Started guide.
How long it takes to launch an API product depends on the complexity of the API and specific requirements. It can take less than an hour to publish a prototype API, which is a good way to learn about OpenShift API Management. It takes about a week to complete all implementation steps for launching an API in a way that meets most requirements. With another week or two, optional extras include advanced control of the API product and more customization of the 3scale Developer Portal for that API product.
Instructions: Launching 3scale API products
Experienced API provider workflow for OpenShift API Management
With a basic understanding of how to use 3scale, and after launching an initial 3scale API product, an API provider can create, configure, and publish additional 3scale API products. The following high-level tasks mirror the tasks for launching a prototype, basic or advanced 3scale API product.
However, this part of the workflow is iterative. Initial performance of a procedure can take advantage of default settings. Later, repetition of that procedure as many times as needed incrementally customizes behavior. An introduction to each procedure follows and includes a link to detailed instructions, which are in Red Hat 3scale API Management documentation.
The workflow comprises multiple procedures that an experienced API provider iteratively performs. An initial workflow iteration follows.
- In the 3scale Admin Portal, a 3scale API provider sets up Red Hat Single Sign-On authentication to control access to the 3scale Developer Portal as well as access to 3scale API products.
An API provider establishes, configures, and enables Red Hat SSO authentication.
Prerequisites: In the Red Hat Single Sign-On Admin Console, create a Red Hat Single Sign-On realm. An SSO realm is required to manage authentication for access to the Developer Portal and 3scale API products.
- In the 3scale Admin Portal, a 3scale API provider adds APIs in the 3scale Developer Portal to set up the Developer Portal interface for API consumers.
An API provider adds OpenAPI Specification 3.0 conforming documents for use in a Developer Portal. API consumers use the Developer Portal to access the APIs defined in these documents.
Prerequisites: A document that conforms to OpenAPI Specification 3.0.
Instructions: Providing APIs in the Developer Portal
- In the 3scale Admin Portal, a 3scale API provider sets up a 3scale Developer Portal so it provides a user interface that facilitates the use of an API product.
An API provider sets up the Developer Portal for an API product. A well-structured developer portal and great documentation are key elements to assure adoption. A developer portal is the main hub for managing interactions with API consumers and for API consumers to access their API keys in a secure way.
Prerequisites: A 3scale API product.
Instructions: From zero to hero Developer Portal
- In the 3scale Admin Portal, a 3scale API provider sets up monitoring and analytics for tracking use of an API product.
An API provider designates methods in their API and adds metrics to set access limits for any of an API product’s application plans. For an API backend, methods and metrics can be used to set access limits in the application plan of any API product that bundles the backend.
Prerequisites: An API product that bundles at least one API backend.
- In the 3scale Admin Portal, a 3scale API provider launches an API product to make its operations available to be called by API consumers.
The advanced path for launching a 3scale API product includes setting up authentication, configuring access policies with application plans, and creating an engaging Developer Portal.
- In the 3scale Admin Portal, a 3scale API provider evaluates API product analytics to refine application plans.
An API provider can monitor metrics that indicate the use of your API product. Knowing how a 3scale API product is used is a crucial step for managing traffic, provisioning for peaks, and identifying the users who most often send requests to the API product.
Instructions: Out-of-the-box analytics