Fast Track to Integration

This guide will help you get up and running with 3scale to boost your API in no time at all. You will cover all the key steps to launch your API:

  1. Secure your API
  2. Configure your API access policies with application plans
  3. Engage your developers with a Developer Portal
  4. Go Live

You have a choice of three different paths to take. The prototype path is recommended to get the fastest possible overview of the steps to integrate 3scale. You will also gain a good appreciation of the end-to-end capabilities of 3scale. It is recommended to complete the prototype before you move on, but if you have successfully completed the "Go Live Steps" from the dashboard of your admin console you can skip this path and go straight to the next one.

If you want to go live with your API in production, and time is of the essence, then you will find the basic path covers the majority of your needs. If you have a more complex requirement, or if you have covered the basic path already, then you may be ready to consider the optional advanced options. Remember if you want to use a custom domain and email that these have a long team time, and you should follow the steps in the Go Live section to get them setup as soon as possible.

The timing guidelines depend on the complexity of our API and how many resources you plan to dedicate to the effort. Most of the time will be spent on refining your API and preparing the content for the Developer Portal. If you already have a stable API and documentation content, you can Go Live within a week.

Step 1.

Enter your 3scale Domain Name:

https://{{provider}}-admin.3scale.net

Step 2.

Select your Fast Track path

Prototype Basic Advanced
Less than an hour Less than one week Several weeks
Do this first before the basic path For most APIs this path covers all you need After you have completed the basic path these are optional extras
If you have successfully completed the "Go Live Steps" from your admin dashboard you can skip this path Complete all implementation steps to launch your API in production Advanced control of your API
Complete an end-to-end integration of 3scale with a simple public API Deeper customization of the Developer Portal

Step 3.

Follow the Steps

Secure your API

Access control is the essential first step to ensure that only API calls with valid, and successfully authenticated credentials are allowed access to your API resources.

Prototype

Assuming your API is already publicly accessible within a few minutes you can prototype the 3scale access control layer.

  1. Verify that your API is publicly accessible (once the security layer is in place, you can hide or restrict access to the backend host) e.g. https://www.googleapis.com/freebase/v1/topic/authority/iso/3166-1/alpha-3/USA?filter=/common/topic/description
  2. Go to your Nginx Proxy Integration wizard >API>Settings>Integration>Proxy:
    https://{{provider}}-admin.3scale.net/admin/apiconfig/services
  3. Before you setup your own API, just verify that you can make a test call using the default parameters to the hello-world-api.3scale.net endpoint
  4. Once verified, proceed to enter the Private API host e.g. https://www.googleapis.com:443
  5. Enter the URL path for a valid GET request to make a test call and select "Update & Test" e.g. /freebase/v1/topic/authority/iso/3166-1/alpha-3/USA
  6. Now you can copy the cURL statement, which includes user_key as the default credentials, to make calls from the command line. You can go ahead and play around to make any calls, for example for a smaller subset of the test call response:
  7. http://api.2445579862642.proxy.3scale.net:80/freebase/v1/topic/authority/iso/3166-1/alpha-3/USA?user_key=KEY&filter=/common/topic/description
  8. Note: You can get the API keys from the app detail page of one of the developer accounts
  9. Success! Your 3scale access control layer will now only allow authenticated calls through to your backend API
Basic

For a full production implementation you need to make some fundamental decisions on how you structure your API, and implement 3scale.

You have the choice of several authentication modes for your API traffic. Consult our guide on your options and configure the setting. Once you set this you should not switch auth modes again, because it can easily invalidate existing credentials.

You also have the choice of several deployment architectures for 3scale. The favorite amoung our customers is the API Gateway based on Nginx due to a combination of ease of configuration and performance. This Gateway may be run in the cloud - great to get started quickly but comes with volume limits and additional latency - or on premise - for the best performance and completely unrestricted traffic volume. If you prefer to stick with your existing app stack technologies and languages, or if you want tighter control of the integration then the plugin libraries are a good fit for you.

APIcast Cloud Gateway (Nginx):

  1. Simply follow the steps in the "Integrate your API in 5 minutes" widget in your admin portal
  2. Continue iterating your API configuration (e.g. refining access policies) until you have reached a version you are happy with for production
  3. Deploy to the APIcast product gateway

On Premise API Gateway (Nginx):

  1. You can follow the Quickstart guide for Nginx if you like more details than in the prototype steps. This guide also covers some of the ground to configure API access polices
  2. Setup up a test installation of your API Gateway on your servers, following the instructions on running your proxy on-premise towards the end of the page. For now we will keep using the API gateway in the staging environment rather than the on-premise API Gateway, because it is faster to test out API config changes in this mode
  3. Continue iterating your API configuration (e.g. refining access policies) until you have reached a version you are happy with for production
  4. Do a final download of your Nginx conf files and deploy to your production Nginx server

Code Plugin Deployment:

  1. You can follow the Quickstart guide using Plugin Libraries. This guide also covers some of the ground to configure API access polices
  2. Choose the appropriate library for your language
  3. The sample code snippets to make authorization calls are available directly in your console under >API>Settings>Integration>Plugin
  4. Whenever you need to do any troubleshooting it is best to start by comparing the plugin behavior to the raw REST API calls using ActiveDocs: https://{{ provider }}-admin.3scale.net/p/admin/api_docs
Advanced

Nginx Deployment:

  • The combination of Nginx with Lua gives unlimited API tranformation options. For some inspiration see our developer blog on how to augment your API

Code Plugin Deployment:

  • Almost all customers find performance to be fine, but if you want to really turbocharge your API, you can cache authorization calls to 3scale. You can use any caching library which you are comfortable with. For a drop-in external cache you can use the 3scale Varnish module with the configuration file: vcl/default_3scale_simple.vcl

Configure your API access policies with application plans

In the previous step you ensured that only authenticated calls are allowed through to your API. Now you will apply policies to differentiate rate-limits.

In 3scale terminology applications define the credentials to access your API. An application is always associated with one application plan which determines the access policies. Applications are stored within developer accounts - in the basic 3scale plans only a single application is allowed, while in the higher plans multiple apps are allowed.

Prototype

In this example we will add a policy to the previous example for Google Freebase:

  1. Go to your API configuration: https://{{ provider }}-admin.3scale.net/admin/apiconfig/services
  2. Select the Basic Application Plan to edit one of the plans that was generated by the sample data after signup to 3scale
  3. Select Limits on the Hits row and edit the existing rate limit to 3 per hour
  4. Now update the Application plan
  5. Go to one of your sample developer accounts (https://{{ provider }}-admin.3scale.net/admin/buyers/accounts) and make sure that the application is set to the Basic plan, and if not Change Plan on the application detail page
  6. Use the credentials for this app and repeat the previous sample call at least 3 times
  7. Success! You have defined more restrictive access polices for all the applications on the Basic plan
Basic

In the prototype you only controlled access based on overall hits on your API. The real flexibilty of 3scale is realized once you use custom methods and metrics to create more sophisticated tiers for your application plans, and for deeper analytic insight to your API. As a brief background you can check the Quickstart guide on Analytics. A few tips are worth bearing in mind:

  • The mapping between your API structure and methods or metrics in 3scale is a logical one, and as long as you can define a consistent rule you can report the usage to 3scale - in effect you determine the level of detail, and generally it is good to aim for 5-20 methods/metrics
  • The values reported to 3scale can only be incremented, and you cannot set absolute values nor decrement the counters
  • After adding any new methods or metrics to 3scale, it is important that you add the new system names to your integration point (API gateway or code plugin)
  • Any changes such as rate limits can be done on the fly with no need for any redeployment

In this example we will add polices to the application plan of the previous example for Google Freebase:

  1. Go to your API configuration: https://{{ provider }}-admin.3scale.net/admin/apiconfig/services
  2. Select Basic to edit one of the plans that was generated by the sample data after signup to 3scale
  3. If you have a rate limit for "Hits", just remove that
  4. Add a New method to the plan with the system name "USA"
  5. Set a rate limit for the method, "USA" of 5 per hour
  6. Add two New metrics with system names "v1" and "v2"
  7. Under the "v2" metric disable access by clicking on the Enabled column (this has the same effect as setting a rate limit of zero

Nginx Deployment:

  1. Go to your Nginx configuration wizard
  2. Expand the mapping section, and add the following mappings
  3. Nginx mapping of methods and metrics
  4. Note: the default mapping for "/" has been edited. If it had been left in place it would lead to double counting of hits.

Code Plugin Deployment:

  1. Follow the instructions and examples in your plugin library to add usage for custom methods and metrics to your 3scale authorization and reporting calls.
  2. Ensure a mapping from the URL structure to the custom method, "USA"
  3. Ensure a mapping from the URL to the custom metrics, "v1"/"v2"
Test the calls using application credentials which are associated with the Basic plan:
  • Calls will be allowed for:
    http://api.2445579862642.proxy.3scale.net/freebase/v1/topic/authority/iso/3166-1/alpha-3/USA?user_key=KEY&filter=/common/topic/description
  • Calls will be rejected because "v2" is not allowed for the Basic plan for:
    http://api.2445579862642.proxy.3scale.net/freebase/v2/topic/authority/iso/3166-1/alpha-3/USA?user_key=KEY&filter=/common/topic/description
  • Calls will be rejected because "USD" is not mapped for
    http://api.2445579862642.proxy.3scale.net/freebase/v1/topic/authority/iso/3166-1/alpha-3/DEU?user_key=KEY&filter=/common/topic/description
  • Note: calls will be allowed for Nginx (for your plugin it depends how you implement the mapping) for the following call - it would be up to your app to return a 404 Not Found response. You can always refine the mapping to avoid this:
    http://api.2445579862642.proxy.3scale.net/freebase/v1/topic/GARBAGE/iso/3166-1/alpha-3/USA?user_key=KEY&filter=/common/topic/description

This basic concept gives you all the flexibility you need to define your API tiers. The important thing is to decide early on what you want to use for your custom methods and metrics. Whenever you make changes to the system names you need to redeploy the changes as described in the Secure your API section.

Advanced

Alerts may be configured to send notifications out by email or to the web consoles. Go to your API configuration: https://{{ provider }}-admin.3scale.net/admin/apiconfig/services. Then select Alerts and select the alert levels you desire as a percentage of your rate-limit levels.

3scale gives you the flexibility to decide whether to make rate-limits soft (even calls above the limits are allowed through) or hard (calls are rejected before hitting your app). With the code plugin you conciously need to decide which type to implement. On the other hand Nginx defines hard limits by default. These can be customized in the Lua file to avoid rejecting over-limit calls

Engage your developers with a Developer Portal

Most best practice surveys are unanimous that a good Developer Portal and documentation are essential for fast adoption of your API.

Prototype

For the prototype you don't really need to do create any documentation content. It is usually enough to check that the workflows will meet your requirements. For example while the API is in development and testing you may like to disable the full self-service workflow:

  1. From your admin console go to the view of your Developer Portal seen by your developers, by clicking Site in the top right menu.
  2. Create a test signup and walk through all the steps.
  3. Normally self-service is enabled by default, so to change that go to your Settings (https://{{ provider }}-admin.3scale.net/admin/site/usage_rules/edit)
  4. Check the box for Accounts require approval?
  5. Now you can repeat the test signup walkthrough and verify that you need to approve the account in the admin console before the user can log in.
  6. Success! You can customize workflows for your Developer Portal.
Basic

The Quickstart Developer Portal guide contains almost all you need to complete a Developer Portal. A useful tip is to consider writing your content in Textile or Markdown. Some of the optional steps that you may like to consider for completeness:

Advanced

Two advanced areas to explore for the Developer Portal:

  • Liquid markup provides tags and drops which give you direct access to system objects and allows you to introduce dynamic rendering of Developer Portal pages.
  • 3scale system pages can all be customized. This is a topic for very advanced users, because the HTML is rather complex. Ultimately if you want the maximum personalization you can customize virtually any page of your Developer Portal. Normally you will find the default pages are perfectly fine with some CSS changes.

Go Live

The final checklist before the public launch of your API (remember to request the custom domain and email as soon as possible, because they have a long lead time):

  1. Setup a custom domain (optional and only if you are on a paid 3scale plan)
  2. Setup a custom outbound email address (optional if you are on a paid plan)
  3. Remove the Developer Portal access code: https://{{ provider }}-admin.3scale.net/admin/site/dns

Beyond this point some of the extras that you may want to consider:

  • Add pricing to generate revenue directly from your API
  • Contact 3scale for help to promote your API
  • Use insight from analytics of your API (under Monitoring in your admin console) to refine your Application plans