Cloud Blog

Category Archives: API Cloud

Throttle APIs by IP address, headers, parameters, and JWT claims

We have rolled out Advanced Throttling policies and you can now easily add rate- and bandwidth-limiting based on various parameters including IP address, HTTP headers, query parameters, and JWT claims.

For example, supposed I have an API for phone number verification created as described in our tutorial.

The API accepts 2 parameters: PhoneNumber and LicenseKey. LicenseKey 0 is a demo key so I would like to limit its use: if subscriber supplies 0 as LicenseKey I want to only allow 1 call per minute. For any other key, I will allow 1000 calls.

Here’s how I can set this up in API Cloud:

We will first start by defining the new throttling policy:

1. In API Cloud, click the Configure / Admin Dashboard menu,

2. In the Admin Dashboard’s left-hand menu pane, click Throttling Policies / Advanced Throttling,

3. Click the Add Tier button at the top:

advanced-throttling-policies

4. Give the new policy a name (I called it ‘ThrottleFreeLicense‘) and set the default limits (I set it to 1000 calls per 1 minute):

new-advanced-throttling-policy-and-default-limits

5. Now scroll down to the Conditional Groups section and edit the condition.

Policies can have multiple conditional groups but, in our case, we just need one because we only want to set LicenseKey = 0 as the special case.

You can optionally give it a name (such as ‘LicenseKey 0 gets 1 req/min’) and then select which kind of condition you want to include: IP address, HTTP header, query parameter, or JWT claim.

We will pick Query Param Condition, turn it ON, and then set Param Name to LicenseKey and Param Value to 0.

set-condition

Click the Add button to get the condition added.

6. Now scroll further down and specify the limits when the condition above is met. In my case, when LicenseKey = 0, I want to only one request per minute allowed:

set-policy-limit

7. Finally, click the Save button to update the policy.

Now we need to assign this new policy to our API:

8. Back in API Cloud’s Publisher, open your API for editing,

9. Go to the third step of API editing (3. Manage).

10. In Advanced Throttling Policies, select Apply to API and select your policy (in my case ThrottleFreeLicense) from the drop-down list:

apply-advanced-throttling-policy-to-api

11. Click the Save & Publish button to make the change take effect.

Note: new policies take effect immediately. If you are modifying an existing policy, your changes will likely take about 15 minutes to take effect due to API caching.

Now you can give it a try.

12. Go to API Store and invoke the API either from the API Console tab or a curl command or any other client. You will see that the first invocation with LicenseKey = 0 succeeds while the immediate next one fails:

$ curl -X GET --header 'Accept: text/xml' --header 'Authorization: Bearer ca115527-25a7-3bba-879a-xxxxxxxxxxxx' 'https://gateway.api.cloud.wso2.com:443/t/wso2dmitry2639/phones/1.0/CheckPhoneNumber?PhoneNumber=8888888888&LicenseKey=0'

<?xml version="1.0" encoding="utf-8"?>
<PhoneReturn xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://ws.cdyne.com/PhoneVerify/query">
<Company>Toll Free</Company>
<Valid>true</Valid>
<Use>Assigned to a code holder for normal use.</Use>
<State>TF</State>
</PhoneReturn>$

$ curl -X GET --header 'Accept: text/xml' --header 'Authorization: Bearer ca115527-25a7-3bba-879a-xxxxxxxxxxxx' 'https://gateway.api.cloud.wso2.com:443/t/wso2dmitry2639/phones/1.0/CheckPhoneNumber?PhoneNumber=8888888888&LicenseKey=0'

<amt:fault xmlns:amt="http://wso2.org/apimanager/throttling"><amt:code>900800</amt:code><amt:message>Message throttled out</amt:message><amt:description>You have exceeded your quota</amt:description><amt:nextAccessTime>2017-Jan-05 17:14:00+0000 UTC</amt:nextAccessTime></amt:fault>$

Besides exact match conditions (like in my example above) you can also specify IP address ranges and regular expressions for HTTP headers and JWT token claims.

Advanced throttling is a powerful mechanism that allows you to fine tune rate limits and bandwidth based on various API call conditions.

Give it a try in API Cloud today!

Now available in Canada

We are happy to announce that Canada is now one of the gateway locations offered by WSO2 API Cloud.

now-available-in-canada

Canada joins the happy family of other WSO2 Cloud locations that already include the US, EU (Ireland and Germany), Brazil, Singapore, Australia, Japan, South Korea, India, and China.

You can host your APIs in any of these locations or even have a multiregional deployment in which subscribers either get redirected automatically based on their geographic proximity or choose their gateway explicitly.

Alerts on API performance and subscriber behavior

Do you want to be alerted when your API is down? Or when one of your subscribers starts behaving suspiciously invoking the API from a different IP address or in an unusual pattern?

All of this is now easy with WSO2 API Cloud!

Alerts can be configured on two levels: publisher and organization administrator.

The following alerts are available:

You can follow the links above for details on how each of them works.

To configure alerts on the publisher level:

  1. In API Cloud’s left-hand menu, click Manage Alert Types,
  2. Select the alerts that you want to receive,
  3. Specify the email addresses (press Enter after typing each address),
  4. Click Save:

email-alerts-in-api-publisher

To configure alerts on the organization admin level:

  1. In API Cloud’s Configure menu, click Admin Dashboard,
  2. In Admin Portal’s left-hand menu, click Analytics / Manage Alert Types,
  3. Select the alerts that you want to receive,
  4. Specify the recipient email addresses,
  5. Click Save:

email-alerts-in-api-admin-portal

New API Cloud Reports

We have significantly expanded off-the-shelf reports available in API Cloud:

Statistics tab in the Publisher interface now has 16 reports including both new and revamped old ones:

  • Reports now have a nice date picker and give the ability to compare behavior between API versions: for example, you can see whether API performance improved or degraded with the rollout of the new version,
  • API Latency report shows where exactly your API processing time is spent: authentication, call transformation, backend response, or throttling,
  • API Usage Across Geolocations helps identify your global API consumption trends so you can fine-tune your global sales and marketing, or geographic locations of your API gateways,
  • API Usage Across User Agents shows which platforms are being used to invoke the APIs so you can ensure that your documentation, sales, and marketing are in line with your subscribers’ needs,
  • Created APIs over Time helps you see how your project is evolving,
  • Developer Signups and Subscriptions Created over Time reports help see the dynamics of new subscriber acquisition.

Watch the video above for details and try the new reports in API Cloud today!

Log Access in API Cloud

One of the most exciting features of the updated API Cloud is access to logs. Now when one of your APIs or prototypes is not working as expected you can check out the logs and see what is going on.

Now if you need to troubleshoot an API issue simply do the following:

1. In API Cloud’s Publisher interface, on the Configure menu, click Admin Dashboard:

Admin Dashboard menu

2. In Admin Dashboard’s left-hand menu, navigate to Log Analyzer / Live Log Viewer:

Admin Dashboard log viewer

3. Now invoke the API or prototype that you are troubleshooting.

4. Go back to the Log Viewer and see the errors that the log got (in my particular case on the screenshot below, it was API authentication failed):

API invocation error in Log Viewer

With this new feature, it has just become easier to troubleshoot your APIs and make them work flawlessly.

Happy API development!

Upcoming API Cloud upgrade: Oct 23-24, 2016

This coming Sunday, October 23, 2016, we will be upgrading WSO2 API Cloud to API Manager 2.0.

Upcoming upgrade will bring multiple improvements and new feature including beautiful responsive user interface and direct log access.

Here’s quick information about the maintenance window and impact:

Start time: 23rd October 2030 PDT
End time: 24th October 0530 PDT

Expected impact:

  • API Publisher and API Store web UIs will be on maintenance.
  • Your published APIs will continue functioning as normal.
  • There is a possibility of some data loss in statistics for API calls made during the upgrade.
  • All your data including configuration, APIs, subscribers and so on will be migrated automatically.
  • The only required migration from your side would be your custom theme in API Store (Developer Portal). It can be pre-migrated by you to avoid impact on your subscriber community. Please contact API Cloud support if you need to do that but have not received the instructions yet.

API Cloud 2.0 Developer Portal

 

 

Customized Emails to API Subscribers

Branding is a vital part of any API program. WSO2 API Cloud has for a long time provided a way to use custom URLs and visual style for your developer portal.

We are now extending it one step further and also letting you customize the emails that your API subscribers receive from you.

You can customize both the:

To customize the emails you need to supply:

  • New text for each email. The text may include hyperlinks and other formatting.
  • You logo image for the header: width: 251 px, height: 75 px.

By default, the emails look like this:

API-program-invite-default

With customized look and feel you can get your own custom text, logo, and contact information:

API-program-invite-customized

Here is the default text we are sending:

Invitation Emails

Hi,

You have been invited to join<organizaton-name>, which is an organization powered by WSO2 Cloud. You have been assigned the Subscriber role.

Click this one-time link to log in: ….

If you have any questions or need help, please contact us at … or simply reply to this message.

Regards,
WSO2 Cloud Team

Self-Signup Initial Confirmation when Approval is Required

Hi,

The organization <organizaton-name> has not yet approved your request. We will notify you when it’s approved.
If you need any further clarification, please contact <tenant admin’s emailaddress>

Regards,
<tenant-admin’s signature>

When Administrators Reject User Signup Request

Hi,

We regret to inform you that <organizaton-name> has not accepted your request to sign up to their API Store
If you need any further clarification, please contact <tenant admin’s emailaddress>

Regards,
<tenant-admin’s signature>

When Administrators Approve User Signup Request

Hi,

We are pleased to inform you that <organizaton-name> accepted your sign-up request. Please use the following link to log in to the API Store: <user-approval-link>.
If you need any further clarification, please contact <tenant admin’s emailaddress>

Regards,
<tenant-admin’s signature>

 

We do not yet have UI for you to make these changes yourself. So to enable the customization, simply file a support request by clicking the Support menu in API Cloud. We will respond and make the configuration changes for you.

Hiding APIs from Developer Portal

API Cloud lets you control not only who can subscribe to your APIs and invoke them, but even who sees each of the APIs in your API Store (Developer Portal).

The visibility level is set on the first step of the API editing and there are three levels available:

  • Public,
  • Visible to my domain,
  • Restricted by roles

Set API visibility level

Public

Public visibility means that the API will be shown on the Developer Portal to everyone, including not authenticated site visitors.

This is the mode most frequently used for public API programs when you want to have everything available on the website and indexed by search engines, so your API program can attract as big of a community as possible.

Visible to my domain

This option basically means “authenticated users”. Only people who log into your portal can see APIs with this visibility level.

Note that you can control who can do this because the only ways to get an account are to either get explicitly invited by you or to go through self-signup, and the self-signup feature is off by default and can be configured to require approval.

Restricted by roles

This is the strictest visibility control option that lets you narrow down API visibility to a specific group of users.

For example, before making an API publicly visible, you can limit its access to internal developers and quality assurance team.

Or you might have a scenario in which some APIs are visible to the wide ecosystem, more APIs are available to select close partners, and even more are being used internally.

Notes:

  • If you want to use default roles for the visibility – note that their internal names are different from the display names being used in the Members dialog box. So if you want to restrict visibility to publishers only (Members dialog box calls this group: APICloudPublisher) restrict access to publisher role.
  • APICloudSubscriber role is internally simply called subscriber but, in reality, you would rarely use it for restrictions by roles because in most cases the effect of that level of visibility is identical to simply setting Visible to my domain.

Note: API Versions

This visibility control system can be very powerful in combination with API versioning because Visibility setting is applied on the individual version level. For example, you might have version 1.0 of an API Publicly visible, and at the same time only have version 2.0 visible to your Quality Assurance and Beta Testers group, and version 3.0 only visible to Internal Developers.

Global API Gateways

Want to host your APIs in Europe, Asia or South America? We are now starting to let API Cloud customer select regional gateways around the globe to which they want to publish their APIs.

Why

When API Cloud launched initially there was only one location – AWS US East datacenter – in which you could publish your APIs. This has been a problem for some of our global customers for two reasons:

  1. Regulations: while API gateway does not store any end-user data and is merely enforcing policies and passing the calls to the backend, some companies would like to be on the safe side in terms of compliance and keep not just the backend but also the gateway within their jurisdiction,
  2. Performance: if both your backend service and your subscribers are in Australia, having the gateway in the US adds the extra hop to the other side of the globe and the corresponding wait for API consumers.

Today we are excited to announce the availability of API Cloud across the globe.

Where

The following datacenter locations are available:

  • US East,
  • US West,
  • Canada,
  • Brazil (São Paulo),
  • EU (Ireland),
  • EU (Frankfurt, Germany),
  • Singapore,
  • Tokyo, Japan,
  • Sydney, Australia,
  • Seoul, South Korea,
  • Mumbai, India,
  • Beijing, China.

Depending on your API Cloud subscription level, you are able to pick the datacenters that would host your APIs:

Starter Getting Traction Medium Large Extra Large
$129 $298 $698 $2,980 $9,980
US East only Pick any datacenter of choice Up to 3 datacenters Up to 7 datacenters Unlimited number of AWS datacenters of choice

Global API gateways: US, South America, Asia / Pacific, Europe

How it works

  1. You submit a request by filing an API Cloud support ticket and tell us in which regions you would like your gateway to be placed and the custom URL you would like to be used,
  2. We work with you on configuring DNS. The following options are available:
    • All traffic by default routed to a specific regional gateway: for example, a European company might decide that all traffic should go through a gateway in EU.
    • Traffic is routed based on geographic location: European consumers are routed to European hub, Australian – to Australian, and so on.
  3. In addition to this default routing, we can set up gateway URLs specific to regional gateways so you can give your subscribers direct URLs to target your API gateways in the US, Europe, Brazil, Australia, Singapore, India, China, and so on.

Pricing and Availability

There is no extra cost for this feature as long as the number of datacenters you use is within the limits of your subscription level.

The feature is available now to all paying API Cloud customers.

Getting Started

If you are interested in having your APIs hosted in datacenters other than US East – just click the Support menu in API Cloud and let us know. We will be happy to make this configuration change for you.

Categories

Recent Posts

Most Popular Posts