Cloud Blog

Category Archives: API Cloud

Yearly discounts and wire transfer payments

We have made it easier to pay for WSO2 Cloud services (API, Integration, Device, and Identity). When we launched initially, monthly credit card payments were the only option we provided. Now we changed two things:

1. You can pay for a year ahead and save 10% of your subscription price:

2. And, if credit card is not something that your purchasing department likes, you can get a regular invoice and pay via a wire transfer instead:

Whatever is the WSO2 Cloud service of your choice, we would like you to be able to pay for it conveniently (and save money on the way!)

OAuth and Authentication Type: Application vs Application User

On the 3rd step of editing APIs in WSO2 API Cloud, you can set required authentication type for each resource:

We have already covered None as the option to allow invoking APIs without any authentication whatsoever.  Today we will discuss the other options.

Application type means that the API will require OAuth tokens generated with client grant type. That grant type produces tokens specific to the subscription but not the end-users.

So if there is a web- or mobile application that subscribed to this API and it has multiple end-users, they will all be sharing the same token and the API backend will not “know” which end-user is invoking the API:

Application User type means that the API accepts OAuth tokens generated with password grant type. These tokens are specific to the end-user – they require not just the application key but also end-user’s username and password.

In this case, each end-user gets their own OAuth tokens even though they are using the same API subscription. API Gateway then generates a JWT token and uses it to pass application and user information to the API backend:

Application and Application User type means that both kinds of tokens are acceptable by the API.

 

 

 

Limit API access with OAuth Scopes

OAuth scopes are a great way to segregate access to APIs and data. Combined with roles they can also be a powerful way to limit who gets access to what.

Let’s have a look at how you can implement scopes in WSO2 API Cloud.

Sample API

Let’s start with a sample WorldBank API that has two resources: /countries and /indicators – both taking a code parameter:

We have it published in Developer Portal and can invoke either of them with no problem (as long as we are subscribed to the API):

Adding Scopes

Now let’s add two different scopes: one that would only give access to /countries and the other one that only gives access to /indicators.

To do this:

  1. Open the API for editing,
  2. Go to the third step (Manage),
  3. Scroll down and click the Add Scopes button:
  4.  In the Define Scope dialog box, add the wb_geo scope for geographic data:
  5. Repeat the process to add wb_eco scope to the API.
  6. Now you can see both scopes available for the API. Click the + Scope button next to the /countries resource to assign its scope:
  7. Pick Geographic data for /countries and Economic data for /indicators:
  8. That’s it: we defined two new scopes and applied them to two different REST resources. Now click Save and Publish to update the API:

Generate scope-limited OAuth token

Now if you open the API in Developer Portal’s API Console, you will see two things: resources have notes about the scopes they need and attempts to invoke them with a regular OAuth key fail:

To generate an OAuth token with the OAuth scope included:

  1. In Developer Portal (a.k.a. API Store), click Applications,
  2. In the application list, click the application which you used to subscribe to the API (for example, DefaultApplication),
  3. Click the Production Keys tab,
  4. Scroll down to the Scopes section, select the scopes you want (for example, Geographic data), and click the Re-generate button (I picked “-1” as the validity period to have a non-expiring token):
  5. Now if you go back to the API, you can use the new token and successfully invoke the API:

Adding Roles

If you want to limit scope access to particular groups of users, you follow the same procedure but this time also list the roles when adding your scopes. For example, in the screenshot below, I am limiting the wb_geo scope access to users in the researches role:

Multiple endpoints per API

Dynamic Endpoint functionality of API Cloud allows you to dynamically pick the backend to which each call is routed based on the call’s properties.

For example, suppose you have an API that has two resources /countries and /regions:

And suppose the actual implementation of the functionality is at two different backends. /countries is implemented by first.backend.url and /regions by something.different.url.

Fear not, this is fairly easy to implement with API Cloud. You simply need to select Dynamic Endpoint as the Endpoint Type and upload the In Flow sequence that defines the rules to route the traffic:

In our sample scenario, the In Flow sequence might look similar to this:

<sequence name=”dynamic_ep” trace=”disable” xmlns=”http://ws.apache.org/ns/synapse“>
    <switch source=”get-property(‘To’)”>
        <case regex=”.*/countries/.*”>
            <property name=”service_ep” value=”https//first.backend.url“/>
        </case>
        <case regex=”.*/regions/.*”>
            <property name=”service_ep” value=”https://something.different.url“/>
        </case>
        <!– add endpoints as needed –>
        <default>
            <property name=”service_ep” value=”http://some.default.url”/>
            <!–default endpoint if required. However there should be a matching resource–>
        </default>
    </switch>
    <header name=”To” expression=”get-property(‘service_ep’)”></header>
    <property expression=”get-property(‘service_ep’)” name=”ENDPOINT_ADDRESS”></property>
    <!–Please note that “ENDPOINT_ADDRESS” (additional) property is defined here in order to populate
    destination address for statistics (API Usage by Destination). –>
</sequence>

You can obviously define more complex rules if needed.

Do you have multiple backend services that need to become a single API? Dynamic Endpoints can get you going!

 

Now with WebSockets

WSO2 API Cloud now fully supports publishing WebSocket APIs. WebSocket is a TCP-based protocol that is a part of the HTML5 specification, enables full-duplex communications and streaming, and reduces network traffic and delays.

In API Cloud, you can now treat WebSockets just the same way as you treat regular HTTP protocols. It is just another option when you add a new API:

The wizard then guides you through the rest of the process so you can define your policies and make the WebSocket endpoint fully managed.

If you need details, just read this API Manager tutorial that covers the functionality: Create a WebSocket API – now this page applies to API Cloud as well.

Custom API error messages

When API subscribers make mistakes during API invocation be it a wrong REST path, submitting an invalid OAuth key or going beyond the throttling limit – they get an error message like:

{“fault”:{“code”:900902,”message”:”Missing Credentials”,”description”:”Required OAuth credentials not provided. Make sure your API invocation call has a header: \”Authorization: Bearer ACCESS_TOKEN\””}}

We now allow WSO2 API Cloud customers to change these messages so you can have something like:

{
 “errors” {
“status”:900902,
“message”: “Make sure to pass OAuth key as Authorization Bearer. Confused? Read our documentation and samples at our.wonderful.dev.portal”
     }
}

 

Custom messages work for both JSON and XML responses.

Making the change is easy: submit a ticket via API Cloud‘s Support menu, let us know which messages you want to be changed, and our engineers will get your custom messages into the system.

This nicely affects other branding options that we have such as custom URL, custom developer portal theme, and custom emails.

Download SDKs for Your APIs

WSO2 API Cloud now automatically generates and allows API subscribers and publishers to download Software Development Kits (SDKs) for any of the published APIs. SDKs are a great benefit for developers because they provide native programming libraries that give natural access to the APIs within the application code.

SDKs are available both in the Developer Portal (aka API Store) and Publisher.

Developer Portal

Inside the Developer Portal, subscribers simply need to browse to the API they need and click the SDK tab:

Publisher

Within the Publisher UI, simply open the API for editing, and then click Edit Source on the first step of the editing wizard:

You can then use the Generate Server menu to get a stub for the server-side implementation of the API:

Or Generate Client for the client-side SDK:

Availability

We have upgraded WSO2 API Cloud to the new version that contains this feature and it is available to all API Cloud users at no extra cost and with no additional configuration required.

Check it out and let us know what you think.

Swapping version and context in API URLs

By default, APIs published in WSO2 API Cloud get URLs like http://{base-gateway-URL}/{API context}/{API version}/{API resources and parameters}. For example, if the custom URL that you assigned to your gateway is api.my.domain, you might get something like http://api.my.domain/stats/1.0/countries/us.

But what if you want to place the version number first and have something like http://api.my.domain/1.0/stats/countries/us instead? This is trivial too. Simply type {version}/stats (or whatever your API context is) instead of just stats as the context on the first step of API creation:

And you can remove the version number altogether by selecting the Make this the Default Version checkbox on the 3rd step of API creation:

WSO2 API Cloud is a powerful API management platform that allows you to easily create the exact API program you need!

Change in internal username format

I have a quick announcement to make today. After a recent update of WSO2 Cloud, the internal representation of usernames changed and we no longer replace the @ sign with a dot in them.

With that change, your fully qualified username now looks like email@organization_domain. For example, if my email is user@wso2.com and my organization domain in WSO2 Cloud is wso2cloud my fully qualified username would be user@wso2.com@wso2cloud

As you know, in most cases, you simply log into WSO2 Cloud with your email address. This is not changing in any way.

However, there are a few cases in which the internal, fully qualified login comes into the picture:

As I already mentioned, nothing changes for regular cloud login process: you simply keep using your email address there. The change only applies to the 5 advanced scenarios listed above.

Let us know if you have any questions or concerns.

Separating Development, Test, and Production

API programs typically have multiple teams involved: developers, quality assurance, acceptance testing, operations, and so on. Let us talk about the possible approaches to separating WSO2 API Cloud environments in order to give these teams the access they need while preventing them from interfering with each other’s work.

There are two main approaches that we see our customers take:

A. Setting up isolated API Cloud organizations,

B. Segregating API visibility within one organization.

Let’s look into these in detail.

Isolated API Cloud organizations

Separate API environments by provisioning separate organizations

Use this approach if you want to give your teams (for example, Developers and QC) full autonomy and reduce the risk of one team accidentally interfering with the work of another.

  1. You simply purchase separate WSO2 API Cloud subscriptions for the environments that you need. To create these extra organizations in WSO2 Cloud, click the Organization menu (in the 9-dot menu in the top-right corner) and click the Add Organization button.
  2. Upgrade each of the organizations,
  3. Invite team members to the organizations that they need.

Notes:

  • You can use different subscription levels for different organizations. For example, you might need the Large subscription plan for Production but pick Starter for the Developer organization in order to optimize costs.
  • One can be a member of multiple organizations. In that case, they will be prompted to choose their organization at login.
  • You can use Export / Import functionality to move APIs between the environments.

Segregate API visibility within one organization

Separate APIs by assigning roles and setting API visibility

Choose this option if you want to fit the implementation within one subscription and are planning to assign team members to proper roles and ensure proper permissions set for each API.

  1. Create the roles that your organization has such as Developers, QA, Operations,
  2. Assign these roles to your team members,
  3. When publishing APIs, you set visibility to these roles: for example, if there is a new version of an API that is in testing, maybe only QC sees it.

In that scenario, all team members will be sharing the same WSO2 Cloud organization but the APIs and API versions that they see will depend on their role membership.

If you need any help from WSO2 on deciding which option is right for you, simply click the Support menu and ask for assistance.

 

Categories

Recent Posts

Most Popular Posts