Quickstart: Hello World API
Follow all our Quickstart guides to get up and running in no time:
- Hello World API Nginx – this page.
- Hello World API Plugin – for an alternate guide if you prefer to use the 3scale plugin libraries
- 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 the Nginx reverse proxy as your API traffic gateway, but you can follow a similar flow with other integration methods including Varnish Cache, plugin or one of the supported CDN. See the Deployment section for information on these modes. If you prefer to use the plugin libraries to integrate with 3scale (for example you are more comfortable to do the integration within your application) then the alternate Hello World API guide will help you.
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.
- Integrate your API with 3scale using the Sandbox Nginx proxy. (Only for development)
- Map your API URI’s to 3scale methods and metrics
Step 1: Configure a Plan and create your first API Key
Logging into the 3scale admin console (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 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.
Navigate to the API and then the Application Plans Section
Navigate to the API tab, and 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. After clicking save for the new Application Plan, 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 analytics 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”.
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 unique key to access the API. Upon clicking save, select the application and note down the following value (see Figure 11):
- User Key
If your account has been configured for App-id&App-key set or OAuth these credentials may take a slightly different form.
These are the keys the “World Curious” app will use to call the Hello World API. Lastly on the right hand side (see Figure above), select the change plan dropdown and select the plan you created and named earlier (“HelloWorldTest” 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 Nginx Sandbox Proxy
Once you sign into your 3scale account, select “Launch your API” on the main Dashboard screen or go to API→Select the service (API)→Integration in the sidebar→Proxy
Set the address of of your API backend. This is the address of the server where your API is running. Now you can input some valid resource path of your API which will be used to validate the sandbox proxy. After that save, turn on and test the sandbox proxy. If everything goes fine the sandbox proxy process will turn green and You will get also see the full test call made to verify connection. It will be of form: curl http://sandbox-endpoint/getHello.xml?user_key=USER_KEY
where, USER_KEY is the key of one of the sample applications which you 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, next with incorrect credentials, and then once authenticated within and over any rate limits that you have defined.
Step 3: Capture traffic for specific methods
By default we start with a very simple mapping rule,
This rule says, that any
GET request that starts with
"/" will increment the metric
hits by 1. Most likely you will remove this rule since it is too generic.
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 Hello World API that serves us as an example:
We are matching two methods from your API, which you earlier defined in your Application Plans. They are done via a literal string
The workflow to define mapping rules is as follows:
Add new rules clicking the Create Rule button. Then you select an HTTP method,
a pattern, a metric (or method) and finally its increment. When you are done, click save.
Mapping rules will be grayed out on the next reload to prevent accidental modifications.
To edit an existing mapping rule you must enable it first by clicking the pencil icon on the right. To delete it there is the trash icon. Edits and modifications (deletions also) will be saved when you hit the save button.
Now you can repeat traffic testing for the mapped methods and check their traffic in the Monitoring section of your admin console
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 and you have a working integration with your Sandbox, you can deploy your own hosted Nginx solution for production. The HowTo’s on that you can find here (they also include more details and some troubleshooting tips on the sandbox proxy):
You can also 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
Closing the Loop
In the example, the new API credentials were generated from the management console to keep things simple. Once you have setup a Developer Portal, 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 Setup Nginx as an API Proxy in the Troubleshooting section in the end of the HowTo to check some possible solutions. If that doesn’t work, check our Forum to get the information you need.