Chapter 2. API traffic with 3scale
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 will 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.
2.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 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.
2.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.
2.2.1. Defining your API and creating 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.
2.2.1.1. Defining your API: Add metrics and methods
Here you can add as many methods and metrics as you need. By default, they will 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 defining your API on 3scale.
For this simple test, add just two methods under hits with system names:
- gethello
- getgoodbye
2.2.1.2. Configuring limits 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. 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.
2.2.1.3. Creating 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 Admin Portal, 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, and confirm the change. This applies the new plan to this application.
You have now configured the management system for your first application.
2.2.2. Integrating 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, click Update & test in Staging Environment. 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, create a developer account and an application within that account.
Try the integrated API without app credentials, then with incorrect credentials. Then once authenticated, try to send API calls within and over any rate limits that you have defined.
2.2.3. Capturing traffic for specific methods
By default you start with a very simple mapping rule.
This rule says that any GET request that starts with forward slash (/) will increment the metric hits by 1. You will most likely remove this rule since it is 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 are 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.
2.3. Results
Your API is now connected to 3scale. You can now apply API management features to manage and track your API traffic.
2.4. Closing the loop
In the example, new API credentials were generated from the Admin Portal to keep things simple. Once you have set up a developer portal, new developers can use the it to automatically create accounts and receive their credentials.
2.5. Help
If you have trouble setting up your API, head over to the troubleshooting tutorial.
Additional resources
Now that you have 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:
