Cloud Blog

All posts by Dmitry Sotnikov

Dmitry Sotnikov is Vice President of Cloud solutions at WSO2. Prior to WSO2, Dmitry worked at Quest Software (now part of Dell) as Director of Cloud Solutions, and later co-founded Jelastic PaaS and led Jelastic's sales, marketing, customer and partner relationships. Dmitry has been a featured speaker at multiple industry events including Microsoft TechEd, VMware VMWorld, Parallels Summit, Quest Innovate, and Technology Experts Conference (TEC).

How API Gateway constructs URLs and translates them to backend calls

The URLs that your APIs have when hosted in API gateway and exposed to the world are different from the URLs of the backend services. Today we will explain how API gateway translates the calls that it gets into what it invokes and how each piece of that URL can be modified.

We will be looking at a simple case of one-to-one translation when you just want to pass parameters and values to the backend as they are (you can modify them on the fly too – see some links at the end of the post):

  1. API subscriber invokes something like apis.example.com/directory/1.0/users?identifier=123,
  2. If apis.example.com is associated with your organization in API Cloud, the API gateway receives the call,
  3. From the API context (directory) and version (1.0), the gateway identifies which API it should be calling,
  4. The gateway “knows” the Production Endpoint for that API (or Sandbox Endpoint if that is what is being invoked),
  5. It takes that endpoint and appends the resourceparameters, and values to it.
  6. The gateway then passes that call to the backend.

Let’s look at the elements of the API URL that the subscriber is invoking in the cloud:

  • API gateway URL (in our example, apis.example.com) is the URL part that all your APIs will share. By default, API Cloud will assign you something like gateway.api.cloud.wso2.com:443/t/orgid/ – but you can easily change it to your own custom URL,
  • Context is the URL path of that specific API (in our example, directory). All the REST resources of this API will share it (for example, directory/users directory/books, directory/groups). You specify that value on the first step of API design, right after the user-friendly name:

  • Version is defined on that same step, right after the Context. If you do not want the version to be a part of your API URL at all, you can select the Make this the default version checkbox on the 3rd step of API editing:

  • Resource is the HTTP noun that you use (users, books, groups, and so on). Just provide the name on the first (Design) step of API design in the URL Pattern box, select the HTTP methods you want to allow for this resource, and click the Add button:

  • Path parameters (for example, /users/123) get added in curly brackets right within the URL Pattern box (for example, /users/{identifier}). Query parameters (for example, /users/?identifier=123) get added by expanding the API resource that you just added, typing the parameter name in the Parameters box, and clicking the Add Parameter button (see the picture below). You can then change the type of that parameter from query to header or formData.

  • The values of the parameters will be provided by API users when invoking the APIs,
  • Finally, we need to specify the backend base path for the API. On the second step of API design (“Implement”), select the Managed API option, and type the backend URL into the Production Endpoint edit box:

See also: If you want to also do some call transformations on the fly, here are a few additional posts on how to do that:

Authenticate End-Users for APIs: LDAP, AD, SAML, Database, Web-Service

APIs are often the backbone of the functionality used by mobile and web-applications. These applications in their turn often need to “know” end-user identity to provide personalized service: end-user-specific data, permissions, access, and so on. How do you get API Gateway to verify that the user is who she claims she is, let her use the API, and pass her identity to the backend?

We have now made it easy with Configure / External Users / API Consumer Authentication configuration screen:

The following options are available:

1. Using existing SAML Identity Provider

Use this option if your application is already SAML-enabled, authenticates with an existing SAML provider, and now just needs to use that SAML token to access the APIs.

The configuration dialog box will ask you for the SAML provider details. Once the configuration is applied, your application will be able to use the SAML Grant Type to get API access OAuth token. When that token is used, JWT with the user identity information will be passed to the backend.

See our SAML Grant Type documentation for details.

2. Directly connecting to an LDAP userstore

If your LDAP directory is visible to API Cloud (for example, you have set up a VPN connection):

  1. Select the Connect your LDAP User Store option,
  2. Clear the Outbound agent configured checkbox,
  3. Specify LDAP connection parameters.

Once the configuration is live, your application will need to use the Password Grant type to get the OAuth token. API Gateway will verify the end-user identity against the LDAP and generate a personalized OAuth token. Each time the end-user accesses the APIs, the gateway identifies the user and passes the user details to the backend via JWT.

See this documentation for details.

3. Connecting to LDAP/AD via Identity Cloud

If your LDAP or Active Directory (AD) is behind a firewall and you do not want to have direct connectivity with it you can use WSO2 Identity Cloud to connect to the directory:

  1. Sign-up for WSO2 Identity Cloud and use its agent to hook up the directory,
  2. In API Cloud’s Configure / External Users / API Consumer Authentication screen, select the Connect your LDAP User Store option,
  3. Leave the Outbound agent configured checkbox selected.

This is sort of a combination of the previous two cases: API gateway is using Identity Cloud as the identity provider to authenticate the user. After which a personalized OAuth token is granted.

See this documentation for details.

4. Verifying user identity via a custom web service

If your end-users are stored in some sort of database or another system that you can expose via a web-service – select the Connect your RESTful Authentication Service option and provide the connection details.

By default, API cloud will be trying to authenticate end-users with a POST invocation with the following JSON payload:

{
	"credentials": {
		"username": "userx",
		"password": "mypass"
	}
}

If the end-user record is valid, API Cloud expects a response with the following JSON:

{
	"response": {
		"status": "true"
	}
}

These formats, however, can be changed using the configuration dialog box.

If the verification is successful, personalized OAuth token is granted for API access, and each API invocation comes with the user-specific JWT token.

See this documentation for details.

 

API Cloud is a powerful and flexible API management system. Should you have any questions, just click the Support menu and we will be happy to help.

Single Sign-On into API Cloud UI

WSO2 API Cloud is a web-based API management suite but you can now also use your corporate identity system to log into its web user interfaces!

To configure the integration, click External Users on the Configure menu:

You can then select one of the two ways to integrate:

  1. Direct integration with your Identity Provider (IdP), or
  2. LDAP or Active Directory integration via WSO2 Identity Cloud.

Here’s a quick overview of how these work.

Integration with an Identity Provider (IdP)

If you already use an identity provider such as Shibboleth, Google Apps, or ADFS, simply pick the corresponding provider from the dropdown list and supply the additional parameters:

WSO2 API Cloud will then start using this IdP to get users authenticated into the Publisher, Admin, and API Store user interfaces:

See our documentation for more details: Configure an External Identity Provider for API Cloud Authentication.

LDAP or Active Directory integration via WSO2 Identity Cloud

In this case, you use WSO2 Identity Cloud agent to get your local directory server connected to WSO2 Cloud.

You then simply tell API Cloud which local groups need to be mapped to which roles in API Cloud: who will be able to publish the APIs, subscribe to them, and so on:

See this documentation for details:Configure an On-Premise User Store for API Cloud Authentication.

Single Sign-On (SSO) makes your API management easier to use and more secure. Try it today in WSO2 API Cloud.

API Cloud now also encrypts data at rest

Security is the cornerstone of successful cloud projects and API management is no exception.

We have for a long time implemented multiple layers of cloud security including among other things encryption of all data in motion, strict tenant separation, fully patched systems, extensive security training and policies for all WSO2 engineers running the cloud.

Today we are happy to announce that one more milestone has been reached in our security journey – data at rest (all the configuration data you create and store) in WSO2 API Cloud is now also encrypted.

What’s even better:

  • This includes not just the US, but also all the regional deployments of API Cloud,
  • There is no impact on your APIs performance (see the response times in our availability dashboard),
  • You don’t have to do anything or pay anything extra: the change is now live for all paying and trial customers.

This is just one of those examples of the service getting better and better all the time.

If you have any questions just contact us and we will be happy to help.

Move query parameters to REST path

Your API backend often does not match the desired frontend representation. For example, it might have extra parameters (such as API keys) that you do not want to expose and have some query parameters that you now want to just include in the REST path.

For example, you might want to do a transformation like shown in the picture below:

Today we will see how easy it is to do so with WSO2 API Cloud.

We will turn a pretty convoluted API from Marvel that looks like: gateway.marvel.com/v1/public/characters?nameStartsWith=name&ts=1
&apikey=d56d63913651985b837b45b4052abd28
&hash=be9591741a837962648744c3de21e4d8
into something like my.api/hero/name.

1. First, we go to API Cloud and start designing the new API.

We create the API as usual, but in URL Pattern field, provide the parameter names that we want to have in the REST path in curly brackets – for example, {name} instead of name:

2. On the second step of the API creation wizard, we paste the backend URL and substitute the parts that we want to be taken from the input parameters with {uri.var.name_of_the_path_parameter}.  So gateway.marvel.com/v1/public/characters?nameStartsWith=name&ts=1
&apikey=d56d63913651985b837b45b4052abd28
&hash=be9591741a837962648744c3de21e4d8
becomes gateway.marvel.com/v1/public/characters?nameStartsWith={uri.var.name}&ts=1
&apikey=d56d63913651985b837b45b4052abd28
&hash=be9591741a837962648744c3de21e4d8
:

3. Now API gateway will automatically insert our name parameter into the backend URL and keep the other parameters intact. However, by default, it will still be adding our path parameter to the end of the backend URL too. With that, we risk invoking something like gateway.marvel.com/v1/public/characters?nameStartsWith=name&ts=...&apikey=...&hash=.../name instead of the gateway.marvel.com/v1/public/characters?nameStartsWith=name&ts=...&apikey=...&hash=... that we need.

Removing that trailing part of the URI is easy. We just need to pass the corresponding command to the gateway transformation engine.

Create a text file with the following text and save it as xml:

<sequence xmlns="http://ws.apache.org/ns/synapse" name="drop_uri_sequence" >
<property name="REST_URL_POSTFIX" scope="axis2" action="remove"/>
</sequence>

To upload the file: select the Enable Message Mediation checkbox, click the Upload In Flow button, and upload the xml file:

4. Now you can finish the API creation wizard and publish the API.

5. In API Store (Developer Portal), you can now subscribe to the new API and invoke it. As you can see, we now get the same results as the original API produces but with a much nicer and shorter invocation URL (which you can make even shorter by setting it as the default API version and using the custom URL functionality):

WSO2 API Cloud (and open source WSO2 API Manager) give you a powerful solution to make your APIs look exactly the way you need them.

Faster ticket resolution through granting access to support team

We know that support experience can be frustrating when the engineer on the other side does not fully understand the exact issue that you are facing and you get into the long back and forth with questions, answers, and screenshots.

There is now a better way! When creating a support ticket, you can now simply select the Allow Access to WSO2 Support checkbox and the engineer that gets your ticket assigned will be able to securely access your WSO2 deployment and troubleshoot the issue:

This new feature radically shortens the resolution time and gets your going with your project faster. And once the ticket is resolved, you can simply go to the Organization screen (in the 9-dot menu) and revoke the access.

 

Display the latest or all versions of an API

By default, API Cloud‘s Developer Portal only displays the latest published version of each API.

So once version 2.0 of an API gets published, version 1.0 gets automatically hidden from the Developer Portal (existing subscriptions still work though until you block the API.)

This way you can make sure that all your new subscribers pick the latest and greatest of your APIs. You can see the video and read more about how API lifecycle works in this tutorial.

However, all API programs are different and you might decide that you want all published versions of your APIs shown to your subscribers. To do that, you need to set the DisplayMultipleVersions flag to true as described in API Cloud’s documentation.

Notes:

  • It might take about 15 minutes before the changes apply to your store and the older versions start showing up,
  • Even with this flag, deprecated versions are still hidden. If you want API Cloud to also show deprecated APIs set the DisplayAllAPIs to true too.

 

Uptime Dashboard now includes regional gateways, Integration, Identity, and Devices Clouds

We have extended our public uptime dashboard to go beyond just API Cloud and its default gateway. From now, on API Cloud’s indicators include:

  • Web interfaces (Publisher, Admin Dashboard, Developer Portal),
  • Key Manager,
  • Developer Portal (aka API Store),
  • Regional Gateways.

Even more importantly, we now have public dashboard indicators for the other WSO2 Cloud services:

  • WSO2 Integration Cloud,
  • WSO2 Identity Cloud,
  • WSO2 Device Cloud.

For all of these, you can see whether the service is up or down at the moment, how well it performed lately, and can even drill down into uptime and performance over the last few months and get a list of all disruptions we had during the selected period:

In addition to the uptime dashboard, all paying customers get incident notification and post-mortem emails as well as maintenance announcements.

WSO2 Cloud comes with financially backed uptime SLA and our public availability dashboards and incident notification processes help ensure transparency of our quality of service and processes.

New and Improved Live Log Viewer

Debugging APIs can be a challenge when things go wrong. A lot can go unexpectedly while the calls travel from a user application to the API gateway, through transformation engine, to the backend service, and back.  Luckily, WSO2 API Cloud comes with a live Log Viewer screen and we have just released its improved version.

Whenever you want to see what’s going on under the hood of API Gateway:

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

2. In the API Cloud Admin Dashboard, navigate to Log Analyzer / Live Log Viewer.

3. Invoke the API that you want to troubleshoot (for example, in the Developer Portal or curl or from your application.)

4. See the log in the Log Viewer:

The new Log Viewer:

  • Has a clear visual separation of information, warning, and error messages,
  • Works across all regional gateways around the globe.

Note:

  • API call tracing is off by default, so you will likely not be able to get the detailed information on the actual API and response URLs, headers, and body. To get those, enable tracing before making the calls. Then turn tracing off when you are done troubleshooting.

 

Adding request headers to published APIs

Suppose you have a REST API and besides parameters also want to prompt subscribers for custom HTTP headers. WSO2 API Cloud makes this easy.

In the example below, we will add a custom header called setName to an existing API and invoke it from the Developer Portal.

1. In API Cloud’s Publisher interface, open the API for editing, and on the second screen (Implement), select the Enable API based CORS Configuration checkbox:

2. In the Access Control Allow Headers edit box, type the name of the header that you would like to add (in our case setName) and press Enter. Then click the Save button.

3. Now, go back to the first step of API editing (Design), open the resource that you want to request that header as a parameter, add the parameter with the name of the header, and change the Parameter Type from query to header:

4. If the API has already been published, you can just click Save to make the change go into effect. If not, go to the last step of the wizard and click the Save & Publish button there.

5. Now, you can go to the Developer Portal (also known as API Store), subscribe to the API if you have not done so yet, and expand the method that we have just modified – you will see that our new header setName is there, listed as one of the parameters:

6. When you invoke the method, you can see that the new header is indeed getting added to the API call and passed to your backend. Notice that the generated curl command example also has the new header:

That is it! WSO2 API Cloud makes it easy to design your APIs the way you want them and have them published for your consumers in a way that is intuitive and easy to understand.

Categories

Recent Posts

Most Popular Posts