Product

Red Hat 3scale 2-saas

For Use with Red Hat 3scale 2-saas

Red Hat Customer Content Services

Abstract

This guide documents product features for Red Hat 3scale 2-saas.

Chapter 1. API analytics

This guide is designed to help you tune your API analytics to track the items you need to know about and to see top applications and trends over time.

Knowing how your API is used is a crucial step for managing traffic, provisioning for peaks, and identifying top users so you can help them achieve greater success with your API.

1.1. Prerequisites

Complete the basics of connecting your API to 3scale before using this guide.

The guide assumes that you are using one of the existing 3scale code plugins to perform an integration. You can follow a similar flow with other integration methods. Check the APIcast Overview chapter of the documentation to learn more about the available integration options.

1.2. Determine the metrics and methods you want to track

3scale acts as an infinitely scalable data repository for your API statistics, and you can track almost any metric for your API. For example:

  • Hits/transactions: calls to the API. Hits are included by default as metrics on all APIs. Hits can be overall calls to the API or broken out into individual methods on the API.
  • Data transfer: quantity of MB/GB of data uploaded and downloaded via the API
  • CPU hours: compute time (or some other internal resource) associated with calls to the API
  • Results returned: count of the number of records or data objects being returned
  • Disk storage: total disk storage in use by an account

You can track more metrics that are relevant to your API. 3scale can track an arbitrary number of metrics and methods, as long as it is a countable quantity that can be incremented over time.

1.3. Create your metrics and methods

After you chose your metrics, register them in the 3scale Admin Portal. Navigate to [your_API_name] > Integration > Methods & Metrics.

Figure 1.1. Create new method

Create new method

Add metrics and methods to the service. Provide them with a friendly name and a system name, which is used later in your plugin configuration. For more details about creating methods and metrics, see defining your API on 3scale.

1.4. Set up reporting

Once you have configured the 3scale system with the names of the metrics to track, it is time to tweak your plugin setup to report the right metrics. The precise manner of doing this depends on the plugin or integration method in use. By default, the plugins report the hits (API transactions) metric only.

Generally speaking, you need to follow these steps.

  1. The application should pass the appropriate metric/method names to the plugin as determined by the incoming API call. The metric/method value and the increment required is an argument of authorize and/or report methods the plugin exposes.
  2. You can also report the traffic using the 3scale Service Management API. You can find information about different endpoints in the 3scale APIs ActiveDocs section. 3scale ActiveDocs are available in your Admin Portal under the Documentation → 3scale API Docs section.

When you report traffic for a specific API method, use the method system name in the metric argument. This automatically increments the counter both for the method reported and the hits metric.

1.5. Check that traffic is reported correctly

Once the API and 3scale connection is established, you can send traffic to the API and watch it register on the API Analytics dashboard. You need an existing developer account and an application with API credentials to be able to perform the steps in this section. Follow these steps to create a developer account and get an application with API credentials.

  1. Open the Getting Started guide.
  2. Navigate to Audience > Applications > Listing to see the list of existing applications.
  3. Select an application by clicking on its name.

    Figure 1.2. Applications

    Applications
  4. Find the API credentials for the selected application. The credentials depend on the selected authentication type and can be a user key (API key), an application ID and application keys, or a client ID and client secret. For more information about the available authentication modes, see the authentication patterns article.

    Figure 1.3. API credentials

    API credentials
  5. Use these keys to make calls to your API in the normal way (for example, from the command line using cURL or from the browser for API endpoints using the GET method). The precise calls to make depend on the structure of the methods on your API. Traffic from these calls appear in the Analytics section for your API.

    Figure 1.4. Analytics usage

    Analytics usage

1.6. Troubleshooting

If traffic does not display on the usage charts in the Analytics section, perform the following checks.

  • Are authorize/report calls responding correctly?

    All plugins call the 3scale Service Management API, which has predetermined response codes. Authorize calls for valid keys should return responses with HTTP code 200. Report calls should respond with code 202.

  • Are there errors in the integration error console?

    The log of integration errors detected by 3scale can be found in [your_API_name] > Analytics > Integration Errors.

    Figure 1.5. Integration errors

    Integration errors
  • Are the correct metric and method names being used?

    The most common reason for failure is that the method and metric names passed in report calls do not correspond to those created in the API settings of your Admin Portal. Check that you are using the correct system names for each metric/method.

1.7. Controlling who sees the analytics

By default, the usage statistics are visible to the API provider through the Admin Portal and to the developers who created applications through the Developer Portal. (Each developer can see only the usage statistics for their own applications.) You have the ability to hide the analytics views from the Developer Portal. See the Developer Portal section to learn more about customizing the Developer Portal.

1.8. Accessing analytics data by API and email reports

Besides the usage graphs in the Analytics section, there are other methods of getting your API’s analytics data.

  • Analytics API

    You can use the 3scale Analytics API. It is a flexible way to extract all the analytics data for your API in either XML or JSON format.

  • Daily and weekly traffic reports (SaaS only)

    These reports provide the aggregated data about your traffic, including information about new subscribers to your API and top applications. To enable these reports in the Account Settings (gear icon) > Personal > Notification Preferences of your Admin Portal, find the weekly aggregate reports and daily aggregate reports check boxes. If enabled, these reports are emailed to the admin user of your 3scale account.

  • CSV export (SaaS only)

    There is a download CSV link on each analytics view page, and you can download the usage statistics in .csv format.

    Download CSV image::guides-api-analytics-download-csv.png[width=100px]

Chapter 2. API Versioning

The 3scale API Management Platform allows API versioning. You have three ways to version your API correctly when you manage your API with 3scale. The following methods are examples of how you could version your API within the 3scale Gateway, which provides extra features due to 3scale’s architecture.

2.1. Goal

This guide is designed to give you enough information to implement an API versioning system within 3scale.

Suppose you have an API for finding songs. Users can search for their favorite songs by different keywords: artist, songwriter, song title, album title, and so on. Assume you had an initial version (v1) of the API and now you have developed a new, improved version (v2).

The following sections describe the three most typical ways of implementing an APR versioning system using 3scale:

  • URL versioning
  • Endpoint versioning
  • Custom header versioning

2.2. Prerequisites

Complete the basics of connecting your API to 3scale before using this quick start guide.

2.3. URL versioning

If you have different endpoints for searching songs (by artist, by song title, and so on), with URL versioning you would include the API version as part of the URI, for example:

  1. api.songs.com/v1/songwriter
  2. api.songs.com/v2/songwriter
  3. api.songs.com/v1/song
  4. api.songs.com/v2/song
  5. and so on
Note

When you use this method, you should have planned since v1 that you were going to version your API.

The 3scale Gateway would then extract the endpoint and the version from the URI. This approach allows you to set up application plans for any version/endpoint combination. You can then associate metrics with those plans and endpoints, and you can chart the usage for each endpoint on each version.

The following screen capture shows 3scale’s flexibility.

Figure 2.1. Versioning Plan Feature

Versioning Plan Feature

The only thing left to do is go to [your_API_name] > Integration > Configuration in your 3scale Admin Portal and map your URIs to your metrics, as shown in the following diagram.

Figure 2.2. Mapping URIs to metrics

Mapping URIs to metrics

You now have two different versions of your API, each with different features enabled. You also have full control and visibility on their usage.

If you want to communicate to all of your users that they should move to the API v2, you can send an internal note asking them to do so. You can monitor who makes the move and see how the activity on v1 decreases while the activity on v2 increases. By adding the metric in your authorization calls to 3scale, you can see how much overall traffic is hitting v1 vs. v2 endpoints and get an idea of when it is safe to deprecate v1.

Figure 2.3. Versioning

Versioning

If some users continue to use v1, you can filter out only those users to send another internal note about switching to v2.

3scale provides a three-step method for sending deprecation notices.

  1. Navigate to Audience > Applications > Listing and filter the list by the application plan that you want to send the deprecation note and click Search.
  2. Click the multiselector to select all of the users for that particular version. New options display and allow you to perform bulk operations, such as Send email, Change Application Plan, and Change State.
  3. Click Send email and follow the steps to send a deprecation notice to those customers who are still under the obsolete version.

The following image provides a visual reference.

Figure 2.4. Sending deprecation note

Sending deprecation note

For each authrep call that is made to an endpoint, you authenticate only once but report twice: once for the endpoint and once for the API version. There is no double-billing because the call can be authenticated only one time. For each call you make to any endpoint of a specific API version, you aggregate the hits on a convenient metric named after the version number (v1, v2, and so on), which you can use to compare full version traffic with each other.

2.4. Endpoint versioning

You have the endpoint change for each version (api.cons.com/author_v1) with endpoint versioning. The gateway extracts the endpoint and the version from the endpoint itself. This method , as well as the previous method, allows the API provider to map external URLs to internal ones.

The endpoint versioning method can only be performed with the on-premise deployment method as it requires a URL rewrite using the LUA scripts that are provided as part of the on-premise configuration.

EXTERNAL

 

INTERNAL

api.songs.com/songwriter_v1

could be rewritten to

internal.songs.com/search_by_songwriter

api.songs.com/songwriter_v2

could be rewritten to

internal.songs.com/songwriter

Almost everything (mapping, application plans features, and so on.) works exactly the same as in the previous method.

2.5. Custom header versioning

With custom header versioning, you use a header (that is, "x-api-version") instead of the URI to specify the version.

The gateway then extracts the endpoint from the path and the version from the header. Just as before, you can analyze and visualize any combination of path/version that you want. This approach has several inconveniences, regardless of the API management system you use. See API versioning methods, a brief reference for more information. Here are a few pointers on how 3scale works.

  • Just like the previous method, custom header versioning can only be applied to on-premise hosted APIs because it requires some parsing/processing of the request headers to correctly route the authrep calls. This type of custom processing can only be done using Lua scripting.
  • With this method, the fine-grained feature separation of the previous methods is much harder to achieve.
  • One of the biggest advantages of using this methodology, and the main reason some API providers choose it, is because the URL and endpoints of your customers will never change. When a developer wants to switch from one API version to another, they only have to change the header. Everything else works the same.

Chapter 3. Getting Started

By the end of this guide, your API traffic will be protected by API keys, tracked, and monitored by 3scale with basic rate limits and controls in place. A fictional "Echo API" serves as an example, which you can substitute with your own API.

Getting your API up and running with 3scale is straightforward and easy to accomplish by following the steps here. You’ll get traffic flowing and monitored as well as be able to issue rate-limited developer keys.

Remember that if you have a production API, you should do this in a staging/non-production environment initially to avoid disruption for existing API users.

3.1. Prerequisites

This tutorial assumes that you are using a 3scale SaaS account and have access to the Admin Portal.

To run this example you can use a simple test API called "Echo API" hosted at https://echo-api.3scale.net.

You’d need to have a simple application, for example "Curious echo," which will call the API. This may be as simple as a command line call, a mobile app, or any code that can call a remote server.

Echo API diagram

3.2. Connecting Echo API to 3scale

In order to connect Echo API to 3scale, you need to follow three simple steps:

  1. Access your 3scale Admin Portal and set up your first plans and metrics and your first API keys.
  2. Integrate your API with 3scale using the API gateway in the staging environment (for development only).
  3. Map your API endpoints to 3scale methods and metrics.

3.2.1. Step 1: Define your API and create your first API key

Your 3scale Admin Portal (http://YOURDOMAIN-admin.3scale.net) provides access to a number of configuration features. For now, focus on getting the minimum setup required to deploy your API:

  1. Define your API: Add the metrics and methods.
  2. Configure any limits you may wish to impose on API usage.
  3. Head to Audience > Accounts > Listing to create a new developer account and API credentials.

3.2.1.1. 1. Define your API: Add metrics and methods

Here you can add as many methods and metrics as you need. By default, they’ll be available in all plans of your service.

Create new method

For more details about how to add methods and metrics, you can check out our documentation page about /docs/access-control/api-definition-methods-metrics[defining your API on 3scale].

For this simple test, add just two methods under "hits" with system names:

  • gethello
  • getgoodbye
Hello world example

3.2.1.2. 2. Configure any limits you wish to impose on API usage

In addition to creating the metrics/methods, you can also add limits to any of the API usage metrics under each plan. Let’s create a new application plan for this example. Navigate to [your_API_name] > Overview > Create Application Plan.

Create application plan

In the form that opens, specify the desired name – for example "HelloEchoTest" – and the system name. Then click on Create Application Plan button.

Echo API application plan

After the previous step, you should see the list of application plans. Click on the "HelloEchoTest" plan to create limits for the metrics and methods. You should be able to see all the metrics and methods that you defined in the previous step. Click on the "Limits" icon under any metric or method. Adding a limit to the Hits metric applies the rule across all the methods under Hits; adding limits to a method only applies to that method. You can create different plans with different limits later on.

Test plan limits

Limits restrict the number of API calls an application on this plan can do per minute/hour/day/etc.

3.2.1.3. 3. Create a new developer account and API credentials

Go to Audience > Accounts > Listing and click on the create button.

Create new account

Fill in some information for the new developer who will access the API.

Input information

Once you click create, select the new account from the list to go to the home page.

The account area lists all the companies and developers signed up to use the API. New companies can be added from the dashboard, from the API, or by self-service signup on the developer portal.

When you create a new developer account, you will also be creating a new application for that account.

See application name

Applications will each have a unique key to access the API. To find that key, click on the application name and check the API credentials section.

API keys and change plans

These are the keys the "Curious Echo" app will use to call the Echo API. Lastly, on the right-hand side of the application details page (see screenshot above), select the change plan dropdown and select the plan you created and named earlier ("Echo Test" in the example) and confirm the change. This applies the new plan to this application.

You have now configured the management system for your first application. For the next steps, make sure you’re using the APIcast hosted deployment option. This option has a staging area where you can easily try out your configuration. === Step 2: Integrate via API gateway in the staging environment

Once you sign into your 3scale account, go to [your_API_name] > Integration > Configuration.

API Gateway staging configuration

Set the address of your API backend in the staging environment. This is the address of the server where your API is running. Now you can input a valid resource path for your API, which will be used to validate the API gateway in the staging environment. After that, hit update & test staging configuration. If everything goes well, you will see a green vertical line in the staging area and the full test call made to verify connection. It will look like this:

curl "https://api-xxx.staging.apicast.io/hello?user_key=USER_KEY"

USER_KEY is the key of one of the sample applications that were created when you first logged into your 3scale account. (If you missed that step, just create a developer account and an application within that account.)

Try it without app credentials, then with incorrect credentials. Then once authenticated, try to send API calls within and over any rate limits that you’ve defined.

3.2.2. Step 3: Capture traffic for specific methods

By default you start with a very simple mapping rule.

Mapping Rules

This rule says that any GET request that starts with "/" will increment the metric hits by 1. You will most likely remove this rule since it’s too generic. You can learn more about how to manage Mapping rules on this documentation page .

The mapping rules define which metrics (and methods) you want to report depending on the requests to your API. For instance, below you can see the rules for the Echo API.

proxy mapping Echo API

You’re matching the API endpoints with the methods, which you defined earlier in application plans.

  • /hello
  • /goodbye

Now you can repeat traffic testing for the mapped methods and check their traffic in the Analytics section of your Admin Portal.

3.3. Congratulations!

Your API is now connected to 3scale. You can now apply API management features to manage and track your API traffic!

3.4. What’s next?

Now that you’ve tested your integration with 3scale in a staging environment, you can select a production deployment option. Find more information about the APIcast gateway in the following documentation:

//// DISCONTINUED: plugin integration is not supported If you prefer to integrate with 3scale though one of the available code plugins, you can find more information about how to set them up and what programming languages are supported on the following documentation pages:

Legal Notice

Copyright © 2018 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.