Chapter 1. Defining Your API (Methods And Metrics)
In this section you will learn how to define your API on 3scale. In order to do so, you’ll need to add your methods and metrics manually on the API > Definition page of the 3scale admin portal, or create them automatically by importing your API specification.
Metrics let you track the usage of your API in 3scale. Hits is the built-in metric, it exists in each API service and is used to track the hits made to your API. You can achieve finer granularity for the API usage tracking by defining Methods under the Hits metric. Reporting traffic to a method will increase counters for the method and for the Hits metric automatically. You can define separate methods for each endpoint of you API, or a combination of endpoint and HTTP method. See Mapping rules section to learn how to map the endpoints of your API to the methods defined here.
For measuring other, not hit-based usage of your API, you can define new Metrics and report the usage in different units. A unit can be anything meaningful: megabytes, CPU time, number of elements returned by the API etc.
Methods and metrics are also the scaffolding to package your API: each application plan lets you define different usage limits and pricing rules for each method and metric.
You will be able to see the the usage reported to metrics and methods in the Analytics section.
1.1. Manually add methods and metrics
Navigate to the API > Definition section of the Admin Portal.
- Click on New method.
Specify the parameters:
- Friendly name is a short description of the method, it appears in different sections of the 3scale admin portal. This name must be unique for the service.
-
System name is the name of the method which will be used to report the usage through 3scale Service Management API. It also must be unique, and it should only contain alphanumeric characters, underscore
_, hyphen-and forward slash/without spaces. Other than that, you are free to decide how the system name will look like, it can be exactly the same as the endpoint ("/status"), or for example can include the method and the path ("GET_/status"). The Description field can be used for a more detailed description of the method, it is optional.
- Finally, click on Create Method button.
You can later change the definition of the method. Just click on the method name (in the column Method), update the fields and click on Update Method.
Be very careful with changing the system name of the methods and metrics or deleting them! It may break your already deployed 3scale integration, if there are mapping rules poining to the previous system name of the method.
For creating a new metric, click on New metric and provide the required parameters. When specifying the unit, use singular noun (e.g. "hit"), as it will be pluralized automatically in the Analytics charts.
These new methods and metrics will be available in all your current and future plans. You can now edit limits and pricing rules for them on each plan going to API
1.2. Import your methods and metrics automatically
If your API has a lot of endpoints, we offer two additional ways of automatically creating your methods and metrics on 3scale:
1.3. Application Plans
Application Plans define the different sets of access rights you might want to allow for consumers of your API. These can determine anything from rate limits, which methods or resources are accessible and which features are enabled.
1.3.1. How to create an application plan
By default, when your 3scale account is created, you are given two plans: Basic and Unlimited. You can keep and edit these or create your own. You can create as many plans as you need.
To create a new application plan, follow these steps:
- Go to the API tab
- Look for the ‘Application plans’ section
- Click on ‘Create Application Plan’
In the next screen, pick a name and a system name (system names must be unique) for your new plan. If the ‘Applications require approval?’ checkbox is selected, no applications will be able to access your API without approval.
Once you’ve created a plan, you can provision rate limits
1.3.2. Setting up a default application plan
After you’ve created all your plans, you can select a default plan for when people sign up to register their applications. To do so, go to API
If you don’t indicate a default application plan, when a new user signs up to get access to your API, they won’t be created an application by default (meaning they won’t really get access to your API).
1.4. Mapping Rules
After you define your API creating methods and metrics, you can map your API endpoints or paths to the methods you’ve just defined in the Definition page.
In order to do so, go to API > Integration and open the Mapping rules section.
Choose the HTTP method, available on the specific endpoint path, and select the equivalent method to map against. Different operations (GET, PUT, POST, DELETE, etc…) on the same endpoint can be tracked separately.
The workflow to define mapping rules is as follows:
Add new rules by clicking on Add Mapping Rule link. Then select an HTTP method, a pattern, a metric (or method), and its increment. When you’re done, click the Update & Test Staging Configuration button.
- Mapping rules will be grayed out on the next reload to prevent accidental modifications.
- To edit an existing mapping rule, you must first enable editing by clicking on the pencil icon on the right. To delete a rule, click on the red trash icon. Edits, modifications, and deletions will be saved when you hit the Update & Test Staging Configuration button.
Once the setup is done, you can test your integration with the Staging APIcast Cloud Gateway to ensure your setup will work in production.
If all the parameters and mapping rules are set correctly, you should see a green line showing a correct test integration between 3scale and your API Backend.
1.5. Provisioning Rate Limits
Rate limits allow you to throttle access to your API resources. You can configure different limits for separate developer segments through the use of application plans.
Once you have rate limits in place, these limits will control the responses a developer receives when they make authorization request calls to 3scale’s backend.
1.5.1. Step 1: Go to the application plan
If you don’t have an application plan defined yet, create one first. Otherwise, select the plan you want to set rate limits for and click “edit”.
1.5.2. Step 2: Set the rate limits
1.5.3. Step 3: Update the application plan
When you’re finished setting the limits you want, make sure to save your changes by clicking “Update Application plan”.
1.5.4. Step 4: Put the new rate limits into action
Now that you have your rate limits defined, the following will happen:
- If you have alerts configured, the new limits will be used to decide when notifications are sent.
- When you make authorization calls to the 3scale backend, the limits will be taken into account. If usage is above the limit, then the response is for an authorization failure. However this is a “soft” rejection, and your app ultimately decides how to handle the rejection
Once your rate limits are operation, you’ll see the users that are reaching the limits on your dashboard, making it quick and easy to check for potential plan upgrade candidates
