Chapter 2. Launching your APIs

In this chapter, you will learn about some key steps to launch your APIs with Red Hat 3scale API Management. To use this guide, there are these assumptions:

3scale has an internal API called API Backend, which is a backend.
3scale has a customer-facing API called Echo API, which is a product. This is the API that you will expose through the Developer Portal.

The guide covers the following steps to launch your API product:

Secure the product.
Configure the product access policies with application plans.
Engage your developers with a Developer Portal.
Go live.

2.1. Paths to launch your first API

To begin working with 3scale, you can choose one of the three paths to launch and expose your API product. Your API product is the customer-facing API you are showing to the world.

The timing guidelines depend on the complexity of your API product and the resources you plan to dedicate to the effort. You will spend most of your time on refining your API product and preparing content for your Developer Portal. If you already have a stable product and content for documentation, you can go live within a week.

These are the paths to launch your first API product:

Prototype

Goal: Complete an end-to-end integration of 3scale with a simple API product, which will be exposed to the public.
Recommended for: This path helps you get a general overview of the end-to-end capabilities of 3scale. You must do this path before going through Basic. If you have successfully completed the onboarding wizard in the Admin Portal, you can skip this path and go to the next one.
Completion time: Less than an hour.

Basic

Goal: Complete all implementation steps to launch your API product in production.
Recommended for: If you want to go live with your API product in production and you have limited time, the Basic path will cover most of your needs.
Completion time: Less than a week.

Advanced

Goal: Optional extras after you have completed the Basic path, such as advanced control of your API product, and deeper customization of the Developer Portal.
Recommended for: If you have a more complex requirement or if you have covered the Basic path already, you may be ready to consider advanced options.
Completion time: Several weeks.

2.2. Following the Prototype path

You can follow through the Prototype path individually from end to end. Alternatively, you can choose to perform some steps from this path according to your needs. Each path can be independent, but Prototype, Basic, and Advanced paths build on top of each other.

2.2.1. Securing your API

You can prototype the 3scale access control layer within a few minutes, assuming one of the following cases:

In 3scale Hosted (SaaS), your product is publicly accessible.
In 3scale on-premises, your product is reachable from the 3scale installation.

Echo API serves as an example of a public product. It has the following features:

It is a simple API that accepts any path and returns information about the request (path, request parameters, headers, etc.) in the response body.
It is accessible at the following URL: https://echo-api.3scale.net
The first time you activate 3scale, a product is created for each existing API. In this first time, there is a one-on-one relationship between the product and the API backend. In other words, you will see: Echo API, a product containing API Backend.

To secure your Echo API product, follow these steps:

Verify that your product is reachable. Example: https://echo-api.3scale.net/v1/fast/track
- After the security layer is in place, you can hide or restrict access to the backend host.
Navigate to [Your_product_name] > Integration > Configuration.
For [Your_product_name], confirm that the private endpoint has been set in the default API Backend. Example: https://echo-api.3scale.net:443
Click the button to promote to staging.
Copy the cURL statement, which includes the user_key as the default credential, to make calls from the command line:
```
curl "https://api-2445581407825.staging.apicast.io:443/v1/fast/track?user_key=287d64924e6120d215b1000ac07c063b"
```
You can make different calls. For example try another endpoint, adding the same user_key.
Note
You can get the API product keys from the application details page, located in one of the developer accounts.
Your 3scale access control layer will now only allow authenticated calls through to your backend API.

2.2.2. Configuring API access policies with application plans

After following the steps under Section 2.2.1, “Securing your API”, only authenticated calls are allowed through to your APIs. In this section you will apply policies to differentiate the rate limits.

In 3scale, applications define the credentials to access your product. An application is always associated with one application plan that determines the access policies. Applications are stored within developer accounts. In the basic 3scale plans only a single application is allowed; but, in the higher plans, multiple applications per account are allowed.

In this example, you add a policy to the Echo API product used in the preceding section with these steps:

Navigate to [Your_product_name] > Applications > Application Plans.
In the Application plans section, go to the Basic application plan to edit one of the plans that was generated by the sample data after installing or signing up for 3scale.
Under Metrics, Methods, Limits & Pricing Rules, select limits in the hits row, and create a new usage limit of 3 per hour.
Find one of your sample applications, by navigating to [Your_product_name] > Applications > Listing. Ensure that the application is set to the basic plan. If not, change plan on the application details page.
Use the credentials for this application and repeat the previous sample call at least three times.

You have now successfully defined more restrictive access polices for all the applications on 3scale Basic plan.

2.2.3. Engaging developers with a Developer Portal

For the Prototype path, you do not need to create any documentation content. It is usually enough to check that the workflows meet your requirements.

While the product is in development and testing, you can disable the full self-service workflow with these steps:

From your Admin Portal, navigate to the Audience space and click Visit Portal link in the Developer Portal menu.
Create a test signup and walk through all the steps.
Usually self-service is enabled by default. To change it, go to Audience > Accounts > Usage Rules and select the account approval required checkbox.
Repeat the test signup walkthrough and verify that you need to approve the account in the Admin Portal before the user can log in.

You can now successfully customize workflows for your Developer Portal.

2.3. Following the Basic path

You can follow through the Basic path individually from end to end. Alternatively, you can choose to perform some steps from this path according to your needs. Each path can be independent, but Prototype, Basic, and Advanced paths build on top of each other.

2.3.1. Securing your API

For a full production implementation, you need to make some fundamental decisions about how to structure your product and implement integration with 3scale.

You have the choice of several authentication modes for product traffic. Consult the guide on the available options and configure the settings.

Important

After you set the authentication, you should not switch authentication modes because this action might invalidate existing credentials.

You also have several deployment options for the API traffic manager layer. APIcast, the NGINX based API gateway, is the favorite amongst 3scale customers due to its combination of ease of configuration and performance. You can use hosted APIcast for a quick start, but comes with volume limits and additional latency. Alternatively, you can deploy it on your own servers for the best performance and completely unrestricted traffic volume.

Hosted APIcast

Follow the onboarding wizard after you log in to your Admin Portal for the first time.
Continue iterating on your product configuration, such as refining access policies, until you have reached a version suitable for production.
Promote your APIcast configuration to the production gateway.

Self-managed APIcast

Set up a test installation of your API gateway on your OpenShift servers.
Continue iterating on your API configuration, such as refining access policies until you have reached a version suitable for production.
Promote your APIcast configuration to the production gateway.
For further details about self-managed APIcast, see Installing APIcast. Additionally, APIcast policies covers some concepts to configure the API access policies

2.3.2. Configuring API access policies with application plans

After following the steps under Section 2.3.1, “Securing your API”, only authenticated calls are allowed through to your product. In this section you will apply policies to differentiate rate limits.

In 3scale, applications define the credentials to access your API product. An application is always associated with one application plan that determines the access policies. Applications are stored within developer accounts. In the basic 3scale plans, only a single application is allowed. In the higher plans, multiple applications per account are allowed.

In Prototype, you can only control access based on overall hits on your product. The flexibility of 3scale is evident after you start using custom methods and metrics to create more sophisticated tiers for your application plans and for deeper analytic insight to your product. For more details, see the analytics guide.

Important

The mapping between your API structure and methods or metrics in 3scale is logical. You can get reports of the product usage from 3scale if you define a consistent rule. You must determine the level of detail. Generally, you should aim between 5 and 20 methods/metrics.
The values reported to 3scale can only be incremented. You cannot set absolute values or decrease the counters.
After adding any new methods or metrics to 3scale, it is important to add the new system names to your integration point, such as the API gateway or code plugin.
You can make changes, such as rate limits, at runtime without redeploying.

In this example, to add polices to the application plan of the Echo API product, perfom these steps:

Find the product you want to work on.
In the Application Plans section, select basic to edit one of the plans that was generated automatically after signing up to 3scale/deploying your instance.
If you find a rate limit for hits, remove it.
Add a new method to the plan under the hits metric with the system name "test".
Set a rate limit for the test method to 5 per hour.
Add two new metrics with system names v1 and v2.
Under the v2 metric, disable access by clicking on the enabled column. This has the same effect as setting a rate limit of zero.

APIcast deployment

Go to [Your_product_name] > Integration > Configuration.
Expand the mapping rules section and add the following mappings:
Note
The default mapping for "/" has been removed. If you use this default mapping, it will lead to double-counting of hits.

Code plugin deployment

To add usage for custom methods and metrics to your 3scale authorization and reporting calls, follow the instructions and examples in your plugin library.
Ensure a mapping from the URL structure to the custom method, test.
Ensure a mapping from the URL to the custom metrics v1 and v2.
Test the calls using application credentials associated with the 3scale Basic plan.
- Calls will be allowed:
```
curl "https://api-2445581407825.staging.apicast.io:443/v1/test?user_key=287d64924e6120d215b1000ac07c063b"
```
  After 5 calls, the calls will start to get rejected. This is because of the limit set for the test method.
- Calls will be rejected because v2 is not allowed in the 3scale Basic plan:
```
curl "https://api-2445581407825.staging.apicast.io:443/v2/test?user_key=287d64924e6120d215b1000ac07c063b"
```
- Calls will be rejected because there is no mapping rule set for missing:
```
curl "https://api-2445581407825.staging.apicast.io:443/missing?user_key=287d64924e6120d215b1000ac07c063b"
```
- These calls will be allowed for NGINX depending on how you have implemented the mapping for your plugin. For the following call, it will be up to your application to return a 404 not found response. To avoid this, refine the mapping:
```
curl "https://api-2445581407825.staging.apicast.io:443/noversion/test?user_key=287d64924e6120d215b1000ac07c063b"
```

This basic concept provides the flexibility you need to define your API tiers, both at the product and backend levels. You should decide early on what you want to use for your custom methods and metrics. Whenever you make changes to the system names, redeploy the changes as described in Section 2.3.1, “Securing your API” for the Basic path.

2.3.3. Engaging developers with a Developer Portal

You can find information to create and provide APIs using the Developer Portal. Consider writing your content in Textile or Markdown. Following are optional steps that you may want to consider:

Configure ActiveDocs to bring interactive capabilities to your documentation and make it easier for developers to explore.
Add a favicon.
Add your Google Analytics tracker code by editing partial in your CMS called analytics.
Configure your signup workflows.
Customize your email addresses (document for 3scale Hosted -SaaS-) and the email template content.

2.4. Following the Advanced path

You can follow through the Advanced path individually from end to end. Alternatively, you can choose to perform some steps from this path according to your needs. Each path can be independent, but Prototype, Basic, and Advanced paths build on top of each other.

2.4.1. Securing your API

To secure your product, you have the following alternatives:

Advanced authentication mode: OpenID Connect (OIDC)

Secure your products using the APIcast integration with OpenID Connect for Red Hat Single Sign-On (RH-SSO). Applications in 3scale are synchronized with the Identity Provider (IdP), in this case RH-SSO. Currently, this is an end-to-end supported solution. It covers the main OAuth 2.0 flows:

Authorization code
Resource owner password
Client credentials
Implicit grant

Code plugin deployment

If you want to increase the performance of your product, you can cache authorization calls to 3scale using any caching library.

2.4.2. Configuring API access policies with application plans

With the options listed under Section 2.4.1, “Securing your API”, you ensured that only authenticated calls are allowed through to your product. In this section, you apply policies to differentiate rate limits.

In 3scale, applications define the credentials to access your product. An application is always associated with one application plan that determines the access policies. Applications are stored within developer accounts. In the Basic 3scale plans, only a single application is allowed. In the higher plans, multiple applications per account are allowed.

Alerts may be configured to send notifications by email or to the web consoles:

Go to your API Settings page: [Your_product_name] > Integration > Settings.
Go to the Alerts section on the page. Here, you can configure the alerts that you want as a percentage of your rate limit levels.

3scale gives you the flexibility to decide on the level of rate limits:

Soft rate limits: Even calls above the limits are allowed through.
Hard rate limits: Calls are rejected before hitting your application.

With the code plugin, you need to decide which type to implement. On the other hand, APIcast defines hard limits by default. These can be customized in the Lua file to avoid rejecting over-limit calls.

2.4.3. Engaging developers with a Developer Portal

After you have completed the Basic path, following are two advanced areas you can explore for the Developer Portal:

Liquid markup provides tags and drops that provide direct access to system objects and allow you to introduce dynamic rendering of developer portal pages.
All 3scale system pages can be customized. This is for advanced users because the HTML is complex. Ultimately, you can customize virtually any page of your Developer Portal. Usually the default pages will be perfectly fine with some CSS changes.

2.5. Going live

This section describes the final checklist before the public launch of your API product.

Note

Raise request for the custom domain and email as soon as possible because they have a long lead time.

Set up a custom domain. For further details, refer to Custom Domain in 3scale Hosted (SaaS).
Optionally, set up a custom outbound email address. To see how to perform this step, see Configure Email Domain.
Remove the Developer Portal access code from Audience > Developer Portal > Domains & Access.

Following are some extra points for consideration:

Add pricing to generate earnings directly from your API product. This feature is only available for 3scale Hosted (SaaS) accounts.
Use insight from your product analytics, in your Admin Portal located under Analytics, to refine your application plans.