Quickstart: Hello World API
Follow all our Quickstart guides to get up and running in no time:
- Hello World API – this page.
- Zero to Hero API Portal – get your API developer portal live and enable signups.
- API Analytics – set up your API Analytics to track method calls and Metrics.
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.
Hello World Example API
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.
Connecting Hello World API to 3scale
In order to connect Hello World to 3scale there are four simple steps:
- Access your 3scale administration panel and set up your first plans, policies, metrics and your first API keys. The admin panel URL will have been provided to you by your account representative and normally initially takes the form http://[company-name]-admin.3scale.net/, later this is moved to a domain of your choice.
- Download and deploy the appropriate code plugin for your chosen language / platform from the 3scale software libraries page.
- Configure the plugin in order to connect to the 3scale systems and report the correct metrics.
- Test traffic with your newly minted API keys.
Step 1: Configure a Plan and create your first API Key
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:
- Navigate to your Account area to retrieve your Provider API Key.
- Navigate to the API and then the Application Plans Section to create a new Application plan for Applications using the API to use.
- Add the metrics and methods on the API you would like to check.
- Configure any limits you may wish to impose on API usage.
- Head to the Accounts area to create a new developer account and API credentials.
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 your Account area to retrieve your Provider API Key
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 and then the Application Plans Section
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.
Create a new Application plan for Applications using the API to use
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.
Add the metrics and methods on the API you would like to check
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.
Configure any limits you may wish to impose on API usage
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.
Create a new developer account and API credentials
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.
Step 2 Download and Install the plugin
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.
Step 3: Configure the Plugin and the Test Application
In order to finalise setup, you can now return to the plugin and add the following elements of configuration:
- Replace the placeholder text for the Provider Key, with the Provider Key you obtained above.
- When calling authorization and reporting methods, you can now use the “system names” you configured for the metrics and methods required. These will be recognised by the 3scale system.
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:
- http://helloworldapi.com/getHello.xml becomes http://helloworldapi.com/getHello.xml?app_id=app_id&app_key=app_key
- http://helloworldapi.com/getGoodbye.xml becomes http://helloworldapi.com/getGoodbye.xml?app_id=app_id&app_key=app_key
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.
Step 4: Test traffic
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:
- Adding more metrics and methods
- Configuring pricing plans and features
- Creating different application plans
- Configuring the public facing portal to enable self signup of developers
- Adapting your plugin deployment to function in asynchronous mode
- And more… – see the complete list of howtos
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:
- Akamai or other CDNs: in this case skip Step 2 (plugin integration is not required), however you will need to setup a CDN configuration file or ESI fragment which is used by the CDN nodes to communicate with 3scale. Depending on your CDN, 3scale will provide you with the right script.
- Software proxies (e.g. Varnish): if your application is running behind a load-balancer or proxy check to see if the proxy is supported by a plugin. In this case installing the appropriate plugin on the proxy means code integration Step 1 is also not necessary.
Closing the Loop
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 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.