Walkthrough of of different product features such as API integration, Analytics, Developer portal, and API environments.
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.
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
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.
- 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.
- 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.
- Open the Getting Started guide.
- Navigate to Audience > Applications > Listing to see the list of existing applications.
Select an application by clicking on its name.
Figure 1.2. Applications
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
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
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
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.
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.
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
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:
- and so on
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
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
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
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.
- Navigate to Audience > Applications > Listing and filter the list by the application plan that you want to send the deprecation note and click Search.
- 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.
- 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
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.
could be rewritten to
could be rewritten to
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.
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.
3.2. Connecting Echo API to 3scale
In order to connect Echo API to 3scale, you need to follow three simple steps:
- Access your 3scale Admin Portal and set up your first plans and metrics and your first API keys.
- Integrate your API with 3scale using the API gateway in the staging environment (for development only).
- 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:
- Define your API: Add the metrics and methods.
- Configure any limits you may wish to impose on API usage.
- Head to Audience > Accounts > Listing to create a new developer account and API credentials.
220.127.116.11. 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.
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:
18.104.22.168. 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.
In the form that opens, specify the desired name – for example "HelloEchoTest" – and the system name. Then click on Create Application Plan button.
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.
Limits restrict the number of API calls an application on this plan can do per minute/hour/day/etc.
22.214.171.124. 3. Create a new developer account and API credentials
Go to Audience > Accounts > Listing and click on the create button.
Fill in some information for the new developer who will access the API.
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.
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.
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. === Step 2: Integrate via API gateway in the staging environment
Once you sign into your 3scale account, go to [your_API_name] > Integration > 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:
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.
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.
You’re matching the API endpoints with the methods, which you defined earlier in application plans.
Now you can repeat traffic testing for the mapped methods and check their traffic in the Analytics section of your Admin Portal.
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: