Packaging APIs for consumers with Red Hat 3scale API Management

One of an API management platform's core functionalities is defining and enforcing policies, business domain rate limits, and pricing rules for securing API endpoints. As an API provider, you sometimes need to make the same backend API available for different consumer segments using these terms. In this article, you will learn about using Red Hat 3scale API Management to package APIs for different consumers, including internal and external developers and strategic partners. See the end of the article for a video tutorial that guides you through using 3scale API Management to create and configure the packages that you will learn about in this article.

About Red Hat 3scale API Management

3scale API Management is a scalable, hybrid cloud API management framework that is part of the Red Hat Integration product portfolio. Figure 1 is a simplified view of the 3scale API Management framework.

The API Manager is the framework's control plane. It provides an interface for the API provider to create users, accounts, policies, and services. The API Gateway (APIcast) enforces the policies for APIs in the data plane.

Policies for  API access

We can use 3scale API Management to create consumer segments where distinct policies are enforced for the same API. For example, let's say we need to expose a single API endpoint to three different consumer audiences: internal developers, external developers, and strategic partners. Table 1 shows a sample scenario of the packages that we could create for each audience.

Note: Although the rate limit is set to "None" for internal developers, it is better to set a high rate limit to prevent distributed denial-of-service (DDoS) attacks. Additionally, while the rate limit for strategic partners is expressed per day, it would be better to set it on a per-minute basis. Doing that would prevent overloading systems with heavy loads in short bursts.

Figure 2 shows the API packages from Table 1.

The Rate limits policy, shown in Figure 2, enforces call limits on APIs. Limits are defined for each method, and the same package can enforce different limits for each API method. Pricing rules are used to enable metering and chargeback for API calls. Pricing rules are defined for each API method, and the same package can enforce different pricing rules for each API method. Finally, the Features policy lets us define multiple features for each package. 3scale API Management adds metadata tags to each package to uniquely identify and map its available features.

3scale API Management's packaging scenario is common, and most API management platforms support something similar. In the following sections, we will look at the different types of plans available from 3scale API Management.

Application plans

Application plans establish the rules (limits, pricing, features) for using an API. Every application request to the API happens within the constraints of an application plan. Every API in 3scale API Management must have at least one defined application plan. It is also common to define multiple plans to target different audiences using the same API. Figure 3 shows the relationship of the API to application plans, consumer audiences, and policies.

Each consumer application is mapped uniquely to a single application plan. When the application requests an API, 3scale API Management applies the rate limits and pricing rules for that application and updates its usage statistics. Application plans are the lowest granularity of control available in 3scale API Management. Most packaging requirements can be met by using one or more application plans per API.

Beyond application plans

In some cases, we need to use specialized plans to define policies for multiple application plans for an API or developer account. A default plan is available to all API providers, but specialized plans—which define complex relationships between services, applications, and accounts—must be explicitly enabled. The decision to use one or more specialized plans should be considered during the API design phase and documented in detail to avoid unexpected outcomes. The next sections introduce service plans and account plans.

Service plans

We can use service plans to subscribe consumers to APIs. Service subscriptions are enabled by default in 3scale API Management, and only one service plan is enabled per subscription. A service plan provides service-level features and plans for all applications consuming the service under that plan.

As an example, the plan described in Table 2 adds a new feature to the application plans we developed in the previous section.

We could set up the new features individually for each application plan. However, it would be better to define the “default” service plan features and enable corresponding features in the application plans as required.

Table 3 describes a more complex scenario, where the API provider needs to provide two or more application plans for partners.

In this case, the API provider could allow a single partner account to sign up for multiple plans. For example, a strategic partner could use the bronze plan for applications in development, the silver plan for quality assurance (QA), and the gold plan for production applications. To provide the partner with standard pricing across all application plans, we could use the service plan described in Table 4.

Figure 4 shows a typical scenario using service plans and application plans in tandem.

To recap, consider using custom service plans for these types of use cases:

• Custom features that multiple application plans can inherit.
• A custom trial period that is applicable across multiple application plans for the same API.
• Set up fees or fixed fees that are applicable across multiple application plans for the same API.

Account plans

Account plans are used to apply subscription criteria to consumer accounts. Instead of managing API access, like application plans and service plans, this plan packages accounts and applies the account plan across all the APIs accessed by a given account. Account plans create "tiers" of usage within the developer portal, allowing you to distinguish between grades of support, content, and other services that partners at different levels receive.

Let's say that an API provider wants to cater to three different partner levels, with policies for each, as shown in Table 5.

The provider chooses to charge a fixed monthly cost and setup cost instead of charging per API or application plan. In this case, it makes sense to have a plan operate at the account level so that the same policies apply to all the APIs and applications associated with that account. The API provider could also create different setup costs and support plans for different sets of customer accounts. Figure 5 illustrates the relationship between account plans and APIs.

3scale API Management provides a default account plan for all developer accounts. The default plan ensures that application access is controlled through individual service and application plans. If you needed to define features for a set of developer accounts independent of the number of applications, you might consider implementing an account plan. Account plans also work well when the setup fee, usage fee, or the length of a trial period is fixed for the account regardless of the number of APIs subscribed.

Watch the video

Watch the following video for a guide to using 3scale API Management to package and combine API plans for a variety of consumers.

Conclusion

As you have seen, it is possible to accomplish many complex API packaging scenarios using 3scale API Management and the right combination of account plans, service plans, and application plans. This article discussed strategies for packaging a single API backend endpoint. 3scale API Management also supports an API-as-a-product functionality that lets us package multiple backend APIs using the same policies and plans. My next article in this series introduces the API-as-a-product functionality and use cases.