Use Case: Controlling API Documentation Visibility with Licenses

This use case provides step by step instructions, and illustrations, for setting up an API and using the Licenses feature to add privacy on certain operations so that different users have visibility of different operations, depending on the user's license.

Except where noted, all setup steps can be completed by the API Admin.

Table of Contents

Licenses use case: overview

This section outlines steps to set up an end to end use case for the Licenses feature.

In this example, we will create an API and use licenses and scopes to control which users have access to which operations.

Rather than providing detailed instructions for each steps, this section links to where the user documentation covers the exact procedure. It includes:

Licenses use case: Setup steps

This use case takes you through a scenario of setting up an API and controlling the visibility of the API documentation by using the licenses feature, including going through all setup steps and demonstrating the results.

Some of the setup actions in this use case require the user to be a Site Admin or Business Admin. These are noted below. If you don't have these permissions, ask your Site Admin or Business Admin for help with these setup steps.

The API description document is included so that you can set this up and run it yourself.

To run this use case you will need:

  • Access to an instance of the API platform, with the ability to create an API.
  • Three valid email addresses for the three users.

In this example, the API has five operations:

  • One POST operation available only to Private Group 1
  • One DELETE operation available only to Private Group 2
  • Three GET operations available to all users (public, no group membership needed).

After setup, the generated API Swagger documentation visibility should be as follows:

  • The API Admin of course sees all operations.
  • Members of Private Group 1 see the POST operation and the three GET operations.
  • Members of Private Group 2 see the DELETE operation and the three GET operations.
  • All users see the three GET operations.

To set up this scenario and see it work, follow these steps:

Create three users:

Notes:

  • If you don't already have a user that can create an API, create this user also.
  • You must be a Site Admin to add users in the Community Manager developer portal. If you're not a Site Admin you would have to create three separate accounts, making sure you use valid credentials and have access to the account.

To create users as the Site Admin: More > Admin > Users > Add User.

Create these users:

  • user1:
    • In this example: user1@rcoaless.com
    • Use a password you will remember
  • user2:
    • In this example: user2@rcoaless.com
    • Use a password you will remember
  • user3:
    • In this example: user3@rcoaless.com
    • Use a password you will remember

Create two groups:

  • Private Group 1:
    • Set visibility to Private
  • Private Group 2:
    • Set visibility to Private

Invite users to groups

  • Invite user1 to Group1
  • Invite user2 to Group2

Create three scopes:

  • Scope 1:
    • Set visibility to Private
    • Clear the OAuth values of Default Scope and User Authorization Required
  • Scope 2:
    • Same settings as Scope 1
  • Free:
    • Public scope (default)
    • Clear the OAuth values of Default Scope and User Authorization Required

Create two licenses:

  • License 1:
    • Set visibility to Private
    • Add Scope 1
  • License 2:
    • Set visibility to Private
    • Add Scope 2

Note: This example does not include QoS policies in the licenses.

Create API:

Create an API by uploading the Swagger file.

Navigation: APIs > Add API. For detailed instructions, see How do I add an API?

Note: The Swagger file provided for this use case is based on the Swagger Petstore API (Swagger 2.0), with some operations removed so that there are only five operations in the file.

API: assign scopes to operations:

Assign scopes to operations as shown below.

Navigation: API > Details > Manage Licensing:

  1. Choose Enable Licensing for API.
  2. Choose Operation-Specific Mapping and assign scopes to the operations as shown below.
To this operation... Assign this scope...
addPet Private Scope 1
findPetsByStatus Free
findPetsByTags Free
getPetById Free
deletePet Private Scope 2

API: invite groups:

Invite both groups to have visibility of the API.

Navigation: API > Visibility > Groups.

API: assign licenses to groups:

Assign the correct license to each group, as shown below.

Navigation: API > Visibility > Groups > select group > Add License.

  • To Private Group 1, assign License 1.
  • To Private Group 2, assign License 2.

Licenses use case: Results

The examples below show the API operations visible to the following users:

API Admin

API Admin sees all operations in the API.

Using licenses/scopes to restrict API documentation visibility: API Admin sees all

User1

User1 sees the POST operation that's linked to License 1 via Scope 1. This is because User1 is a member of Private Group 1, which has License 1 assigned to it.

This user also sees the three GET operations which are public.

Using licenses/scopes to restrict API documentation visibility: user1 view

User2

User2 sees the DELETE operation that's linked to License 2 via Scope 2. This is because User2 is a member of Private Group 2, which has License 2 assigned to it.

This user also sees the three GET operations which are public.

Using licenses/scopes to restrict API documentation visibility: user2 view

User3

User3 does not need to be a member of a group associated with the API, since this user sees only operations not limited to private scopes.

This user only sees the three GET operations which are public.

Using licenses/scopes to restrict API documentation visibility: user3 view

Licenses use case: Training video

The training video below, in two parts, walks you through all steps in this use case, using the Swagger file referenced here: