fb
WSO2 API 3 minutes

WSO2EASY – API Visibility in WSO2 API Manager 2.1.0

Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
WSO2Easy 1
Scroll

WSO2Easy.pngWhen you define an API in the WSO2 API Manager you have three options that will govern API visibility. These options are:

  1. Public
  2. Visible to My Domain
  3. Restricted by Roles

When you define the API you can also determine who can subscribe to an API. The choices here are:

  1. Available to the current tenant only
  2. Available to all tenants
  3. Available to specific tenants

In this WSO2EASY blog we will look at these options and see to what extent they work. For instance, when an API is published as Public but later is changed to Restricted by Roles, does that impact existing subscribers?

There is also the possibility of scopes to be added to the token generation. A user without that scope will not be able to access the API even if they subscribed to it.

Create a tenant

Let’s start by defining a tenant domain because we need that to test the second option. Tenants are defined on the Configure tab in the Management UI of the API Manager. We create the Yenlo.com domain in this example.

Register a new organization - API visibility.png

We also create a role called “pubrole”. This role is empty, no permissions are granted. The role is used to govern visibility as well as used as a scope in the OAUTH2 tokens. Roles can be added to the API Manager using the Main tab Add Users  / Roles.

Add new role - API visibility.png

Similarly create a “testrole” that we will use for scopes.

You will have two roles without any permissions, just a name.

Defining the visibility

All APIs - API visibility.png

Let’s say that we have three API’s:

  1. Pizzashack
  2. WeatherAPI
  3. Rijksmuseum

The Pizzashack API is visible to my Domain, the others are public.

RESTFul API for Pizza Shack - API Visibility.png

Public

A Public API is exactly what it says: an API that actually is available to all users of the public store, regardless of the domain. In order to test you need to be subscribed of course which is only available after login.

WSO2 API Store - API Visibility .png

Restricted to My Domain

In this case the API is visible to the users from the same domain where the api was created in or even imported to. In case of the carbon.super domain (the default setting) you need to log in to the domain to see the API.

WSO2 API Store - API Visibility 2.png

Restricted by Roles

When we change the visibility of the API to “restricted by roles” for the Pizzashack and add “pubrole” as the role that is needed, for non-subscribed users without the “pubrole” the API is not visible. For users who are subscribed it does not change. The API is still visible and the user is subscribed to the API and can still use it.

API Publisher - Warning - API visibility.png

Subscribing

The three subscription options indicate who can subscribe to the APIs. To reiterate:

  1. Available to the current tenant only
  2. Available to all tenants
  3. Available to specific tenants

In conjunction with the visibility you can create a setup where for instance:

  • a public API can be subscribed to by all tenants
  • a public API can be described by specific tenants
  • a domain specific API can be subscribed by the current tenant (so only that domain)

There is some redundancy since an API visible to a domain can only be subscribed to within that domain since otherwise it will not be visible. But with visibility and subscriptions you can actually create special setups.

Invoking an API

Lastly, you might want to have a scope (a role) to be present in the token creation so that even if someone is from that domain, they cannot invoke all of the API’s.

In this case we introduce another role, in this case “testrole” and we create a simple user from the self-signup function. We add “testrole” to that user.

Testrole - API visibility.png

Role List of User - testrole - API visibility.png

In the Pizzashack definition we add a scope (testscope2) with a role of “testrole”.

Resources - API visibility.png

When the user wants to invoke the API once subscribed he or she can see a scope is required.

Invoke API - testscope - API Visibility.png

Without the scope

{
  "fault": {
    "code": 900910,
    "message": "The access token does not allow you to access the requested resource",
    "description": "Access failure for API: /pizzashack/1.0.0, version: 1.0.0 status: (900910) - The access token does not allow you to access the requested resource"
  }
}

With the scope we get a response.

Response with scope - API visibility.png

Conclusion

Visibility, ability to subscribe and scopes help you define API’s with the right level of authorization. However, getting them to work in your envisioned setup will take same time. Hopefully this blog has helped you to set up your environment.

If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product SupportWSO2 Development SupportWSO2 Operational Support and WSO2 Training Programs.