Follow all our Quickstart guides to get up and running in no time:
For Architecture background and a general overview, head to the How it Works section.
By the end of this Quickstart you’ll have traffic on your API protected by API Keys, tracked and monitored by 3scale with basic rate limits and controls in place. We’ll use a fictional “HelloWorld API” example, but you can substitute your own API.
Remember that if you have a production API you should do this in a staging / non-production environment initially to avoid disruption to existing API Users.
The guide assumes that you’re doing the integration using one of the existing 3scale code plugins, but you can follow a similar flow with other integration methods including Varnish Cache or one of the supported CDN. See the “Deployment”/ section for information on this modes. We especially suggest implementation via the Nginx reverse proxy. You can find our tutorial on this in this blog post: Quickstart tutorial on how to deploy an API on Amazon EC2 for Amazon Web Services (AWS) rookies.
In our example we assume you have a simple test API called "Hello World" written in your language of choice running on your server (http://helloworldapi.com/). We also assume you have a simple application "World Curious" that will use the API call - this may be a simple as a command line query, a mobile app or any code which can call a remote server.
A simple API "Hello World" is hosted at http://helloworldapi.com/, an application "World Curious" wants to access the API.
In order to connect Hello World to 3scale there are four simple steps:
Logging into the 3scale management dashboard(http://[company-name]-admin.3scale.net) provides access to a number of configuration features. For now we'll focus on getting the minimum setup required to deploy your API. These are:
At the end of this process you should have the following information:
|Provider Account Key||https://[company-name]-admin.3scale.net/admin/account||This is added to the plugin configuration and is used between your servers and 3scale to authenticate your servers to report traffic to 3scale.|
|System names of Metrics and methods to Track||https://[company-name]-admin.3scale.net/admin/apiconfig/services and from here:
* Select Application Plans.
* Edit Any Plan.
* Edit the metric you would like the name for.
|The system names are used by the plugin to report traffic on the correct metrics and methods.
They should be used as keywords passed to the plugin reporting methods.
|A set of API Credentials||https://[company-name]-admin.3scale.net/admin/buyers/accounts and from here:
* Select the account you are interested in.
* Then the application under this account.
|This is a set of credentials issued for a new user of the Hello World API. They need to be passed to the application in the scenario (World Curious) in order to call the API.|
Navigate to the Account area by clicking on the top right hand side of the administration screen. The provider key is the string shown centrally on the screen.
The provider key is the identifier used for your servers to communicate with 3scale.
Navigate to the API & Plans tab, click on plans and subsequently click on Application Plans - ignore the other types of plans for now. Application plans set policies for applications to access the API.
Once on the application plans view select "new" to create a new plan and fill the resulting form with the required information. Here we assume the name of the plan to add is "HelloWorldTest"- make a note of the name - you will need it shortly.
Clicking create Application plan on the previous screen brings up a creation form for initial data to be added. After clicking save you can create an edit new metrics for the Service this plan is on.
To create metrics/methods, begin by editing the plan and clicking to add a new method for example
Metrics will be tracked by the statistics system and can also be rate limited as well as billed against. Methods are special type of Metric treated as a subtype of the metric "hits".
Each metric and method has a system name. Note down the system names you assign - you will need them later. The hits metric is a special metric which is always present and under which you can create "method" entries. Method entries cannot be created under other metrics.
For this simple test, we suggest you add just two methods under hits with system names:
Creating new methods involves specifying a system name which is needed later for reporting.
Reporting traffic to a method will increase counters for the method and automatically for the hits metric.
In addition to creating the metrics/methods themselves you can also add limits to any of the metrics for usage of the API under this plan - do this by clicking on the "limits" icon under any metric. Adding a limit to a metric applies the rule to the whole metric, applying to a method, only that method. You can create different plans with different limits later on.
Limits restrict the number of transactions per minute / hour / day / etc. an application on this plan can do on the API.
Select the Accounts menu item and click on the new account button. Fill in some test information for the new Developer who will access the API. Once you click save, select the new account from the list to go to the homepage.
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 sign up on the Developer Portal.
Depending on your system configuration you may already see a new application created within the Account. If not, click on the new Application button and provide the required information.
Applications will each have a set of keys to access the API. Upon clicking save, select the application and note down the following two values (see Figure 11):
If your account has been configured for API Key only or openAuth these credentials may take a slightly different form.
You have now configured the management system for your first application.
Software plugins are available in different languages and for a variety of platforms from 3scale: software libraries page. If the language / framework you are using is not available, contact support to see if help is available or you can directly call the 3scale API instead.
Installing the plugin varies for each language. However, at a high level it is normally a library/package that is added to your application and exposes at least two methods: authorize and report. These two methods should be called during the handling of the API calls as they reach the server.
The plugin exposes methods for authorization and reporting which hook into execution of the hello world API.
More information on this step can be found in the Plugin HowTo.
In order to finalise setup, you can now return to the plugin and add the following elements of configuration:
Further, the method calls that previously served to access the API need to be updated in order to capture the API user credentials from now on. E.g. the method call:
The Hello World API code should now refuse calls that do not include the credential parameters and instead upon receiving the call pass the two parameters to plugin authorize method.
In order to test traffic, take the API developer credentials created in the Account area and add these to the World Curiosity application that should now use the amended API calls from the previous section.
The application should now receive correct responses and the application's traffic statistics should appear in the Statistics section of the Admin Dashboard.
Once the Curiosity app is making calls the API, they will become visible on the Statistics dashboard.
Having followed these steps, your API is now connected to 3scale and the various management tools can now be applied to manage and track traffic!
Once traffic is flowing, you can move onto other areas of configuration which include:
This example assumes you are integrating using one of the main code plugins, but if you are integrating using AKAMAI or a software proxy the instructions are slightly different:
In the example, the new API credentials were generated from the management console to keep things simple. Once this loop is closed, new developers can use the Developer Portal to automatically create accounts and receive their credentials.
If you have trouble setting up the API, head over to the Help Zone in the help area to get the information you need.