Licenses: Feature Overview

This document provides an overview of the Licenses feature and how it can be implemented to manage API visibility, define different levels of access, and apply appropriate service level agreements.

It includes information about the feature design, practical implementation tips, and implementation scenarios showing how this feature can be used to benefit both API owners and app developers.

This document is intended primarily for API owners. Some of the activities relating to setting up and maintaining licenses are performed by the Business Admin and some by the API Admin.

Table of Contents

• License feature: overview
• Implementation scenarios
• How the license feature works
• Use case examples
• Licenses feature: end to end use case
• User experience for the app developer

License feature: overview

The platform's Licenses feature gives you complete control over the levels of visibility and access you offer for your API. The feature is designed so that you can exactly customize your offerings, including:

• Who you share with: By using the Licenses feature in combination with the platform's Visibility feature, you can control exactly who can see your API and request access to it. Any defined subset of your API that you designate as Private is only seen by members of groups you specifically invite.
• What you share: You can define one or more overlapping subsets of your API (individual operations or groups of operations) that you want to package separately. Each operation is mapped to one or more scopes. A license can include more than one license term, each of which can include more than one scope, so you can package subsets of your API in different ways. You can then control access to operations and also to the corresponding API documentation.
• Quality of Service: You can determine one or more levels of access you want to offer, for each subset of the API (license term), and define QoS (Quality of Service) policies to match the API access needs of your customer base. This also facilitates monetization of your API. For example, you could offer a limited free service and package broader access for a fee.
• Legal Agreements: You can specify one or more legal agreements to go along with each license. If a legal agreement is defined for a license, app developers must accept the agreement in order to use the API.
• Granularity: You can pull together the above components and package them in different ways as licenses to efficiently manage and monetize your API.

By defining what you want to offer, to whom, and to what level, you can use this feature to design an API offering that suits you and your customers exactly.

Implementation scenarios

The great flexibility of this feature gives you very fine control over your API offering. Below are some hypothetical implementation scenarios showing how you can use this feature to package your API:

1. The ABC Payments API has many small customers as well as one large customer, XYZ Corp. Additional operations requested specifically by XYZ Corp are ready for testing. For a beta phase, the API owner, Tom, wants to release the new operations only to XYZ Corp. The new operations should not even be visible to other customers.

   The Business Admin for the ABC Payments API assigns the new operations to a scope, specifically for ABC Corp, with a visibility setting of Private. All other operations are assigned to a second scope with a visibility of Public. He defines two licenses: one, for XYZ Corp, offers access to both scopes, and the second, for all other customers, offers access only to the public scope. Both licenses offer the same quality of service. The API Admin creates an API Scope Group and invites XYZ Corp. The other customers, not being invited to the private group, are unaware of the new operations. The documentation is tagged with visibility tags for each license, so that members of each user group can see the applicable documentation for the operations covered by their license.

2. The DEF Payments API wants to offer three tiers of service: bronze, silver, and gold. Bronze service includes free access for up to 10 transactions per second, silver service offers up to 50 transactions per second for a small monthly fee, and gold service offers up to 200 transactions per second for a larger monthly fee.

   The Business Admin defines a single scope, All, since access will be granted to all operations. He defines three licenses—Bronze, Silver, and Gold; each has one License Term that includes the All scope and the applicable QoS policy for the tier. The API uses licenses. Privacy is not a factor; in fact, customers need to be able to see all offerings so that they can choose, therefore all scopes and licenses have a visibility setting of Public.

3. The LMN Payments API has two main customer groups with different needs. One group has apps that accept only credit card transactions, whereas the other group has apps that accept only debit cards. For each group, the API owner wants to offer two tiers of service.

   The Business Admin defines two scopes, Credit for credit card transactions and Debit for debit cards. There are two QoS policies, one for smaller customers and one for larger customers, resulting in four separate license offerings; debit card processing at Silver and Gold QoS levels and credit card processing at Silver and Gold QoS levels. In this scenario, the Business Admin sets all four licenses to be visible to all customers.

   The API Admin assigns the Credit scope to all operations relating to credit cards, and the Debit scope to operations that are for debit card transactions.

   Since all the licenses offered are marked as publicly visible, a developer requesting API access sees all four options. The developer chooses the license most applicable to the type of transactions the app processes and the level of service required.

4. The PQR Payments API supports read and write operations. User group A only needs Read access; group B needs read/write access.

   The API owner wants to offer two categories of API access; unlimited read-only access (GET operations), and unlimited write access (all operations other than GET). As part of this, the Business Admin first defines the applicable scopes, and then maps the scopes to licenses. Later, the scopes are mapped to the applicable operations (see below).

   The Business Admin:

   • First, defines two scopes: Update, with a visibility of Private, and then, using the scope hierarchy feature, a child to the Update scope named Read Only, with a visibility of Public.
   • Next, defines two licenses: Gold includes the Update scope, and Bronze includes the Read scope. Read scope is implied in the Gold license because the Read Only scope is a child of the Update scope.
   • Next, invites groups A and B, giving group A visibility only to the Bronze license and group B to both licenses.

   The API Admin assigns all GET operations to the Read scope and assigns all the remaining operations to the Update scope.

How the license feature works

The License feature will work on an API only when the anonymous access on the API is disabled. The anonymous access needs to be explicitly disabled on an API before applying licensing on the API. The license feature encompasses decisions and actions on the part of several key players. Core components (scopes and licenses) are defined within the user interface by the Business Admin, and the API Admin then completes the picture by assigning operations to scopes and inviting license-controlled groups to view the API. Note that all Business Admins are automatically API Admins for all APIs in the business, so the Business Admin can complete both sets of tasks.

Because of the flexible nature of the hierarchy, it is very easy to customize APIs for privacy and monetization. For example, a business can monetize API operations that serve data based on service profiles, or monetize operations that execute transactions based on transaction volume and response time. If you need to make changes, you can modify existing licenses or you can define a completely new set of licenses and leave the older ones in place to support existing customers.

This section provides an overview of the feature in action, including:

• The roles
• The components
• Putting it together

The roles

There are three key roles on the platform that are affected by the Licenses feature. The activities of each, whether with regard to configuration or usage, are as follows:

• Business Admin

  Determining exactly which parts of your APIs you want to expose to which customers, the levels of service you will offer, and the terms of the agreement (monetization) are all key business decisions. For this reason, within the platform the key components of the Licenses feature are defined by the Business Admin. Typically, a Business Admin might be responsible for multiple APIs. In the platform, the Business Admin has the same rights as an API Admin for each API in the business, as well as additional rights, including the ability to set up scopes and licenses.

  The Business Admin defines key components of the Licenses feature including Scopes, License Terms, and Licenses. Once defined, they are available for use by any API in the business. For each API, the API Admin implements the feature by assigning operations to scopes, and manages visibility by assigning licenses to groups.

  For more information on Scopes, License Terms, and Licenses, see The Components below.

• API Admin

  The API Admin is responsible for the API definition within the platform. In the API setup, he or she chooses to use the Licenses feature and then assigns scopes to operations.

  The API Admin also determines the visibility of the API. If API visibility is set to Private, he or she invites one or more groups (API Scope Groups or independent groups) so the group members have visibility of the API.

  API Admins are responsible for tagging API documentation with visibility tags, uploading API documentation, and approving API access requests from developers for their apps.

  Note: Depending on how the platform is set up, individual users might not have permission to create or modify an API unless the user is a Business Admin.

• App Developer

  The main platform user, the app developer, reaps the benefits of this feature with a smooth user experience. When making an API access request, the app developer chooses from a selection of one or more licenses that are applicable for the API.

  For the app developer, it's simply a matter of choosing, out of the licenses offered for the API, the one that most closely offers the capabilities and quality of service that he or she is looking for.

The components

The Licenses feature uses the following components:

• Scopes (in the future, scope definitions will be shared with the OAuth feature)
• License Terms
• QoS Policies
• Legal Agreements
• Licenses
• Visibility
• API Access Requests
• API Documentation Tags

Licenses consist of sets of License Terms that group Scopes with QoS Policies, and Legal Agreements to make up the hierarchy of the License definition. Visibility, API access requests, and API documentation tags are not specifically part of this hierarchy but are key components.

Scopes

A scope is an entity that you define to represent any subdivision of your API that you might want to have separate control of. If you want to have separate control of a specific operation, define a scope that includes only that operation. If you want separate control of READ operations, create a scope for those. The guiding principle in defining scopes is the level of granularity that's needed in defining how the API will be offered to app developers.

A scope is the bridge between the top level of the hierarchy, which is a license, and the bottom level, an API operation (method). The Business Admin defines the basic scope definition. Then, at the API level, the API Admin assigns specific operations to one or more scopes for the API. These operations are included in any license that the scope is assigned to for the specific API.

For example, the Business Admin might define scopes based on roles or groups in an identity management system, since scopes are a way to define authorization policies that become linked to a user's token after authentication. The API Admin then links the scopes to specific functionality within the API by assigning scopes to operations.

When one operation is assigned to multiple scopes, an app developer sees the operation only if that developer has visibility of all applicable scopes. Similarly, an app that's accessing the API must have all applicable scopes in its license or it will not be able to access the operation.

Scope hierarchy

Scopes can be arranged in a hierarchy; a top-level scope can have a child scope, and that child can itself have a child scope.

If scope hierarchy is used, a user who has visibility of the parent scope automatically has visibility to the descendant scopes. Similarly, if an app has a parent scope, Scope1, as part of the access scope for the API, all scopes that are descendants of Scope1 are automatically considered part of the app's access scope.

As an example of scope implementation—the Business Admin might define a scope of All with a sub-scope of Read Only. The API Admin assigns GET operations to the read-only sub-scope and assigns all other operations to the parent scope. A user with access to the sub-scope can use the read-only operations, and another user with access to the parent scope can use all operations.

A scope definition includes scope name, short and long descriptions, and a visibility setting. It also supports some additional settings for any operations that will be assigned to the scope: whether anonymous access is allowed and whether the scope is offered by default to an OAuth grant. If you are not using OAuth you can just ignore the settings relating to OAuth.

Note: In the future, scope definitions will apply to OAuth as well as to Licenses. Currently, OAuth scopes and License scopes are maintained separately.

License Terms

A license term is a custom grouping of scopes and QoS policies. It is essentially the same thing as a term in a business contract. In this case, the license term defines what access is being offered (scope) and the level of access (QoS policy).

To have any impact, a license term must include at least one scope.

A license can include more than one license term.

It's important to understand that the QoS policies apply to the license term, not to the individual scopes within the term. Let's say for example the term includes:

• Two scopes
• One QoS policy that allows up to 10 transactions per second

In this scenario, either scope can process up to 10 transactions per second as long as the combined total number of transactions for all operations in both scopes does not exceed 10 per second.

QoS Policies

QoS policies are a core part of an API definition, and add another dimension to the Licenses feature beyond restricting visibility/access, allowing you to apply use-based policies to your licenses.

QoS policies are defined in Akana Policy Manager by the System Admin. The specific choice of QoS policy, and additional policy configuration steps, include such options as what steps to take when access exceeds the SLA agreement.

Once defined in Policy Manager, they are available in the platform for selection when defining a license term. This allows different QoS policies to be offered to app developers. When making an API access request, the app developer can then choose the license that includes the QoS SLA that he or she needs for the app, and request access at that level. The QoS SLA can then be enforced based on each app-to-API service contract.

A license is constructed as follows:

• QoS policies (0 or more) + Scopes (1 or more) = Term
• Terms (1 or more) + Legal Agreement (0 or more) = License

Legal Agreements

The Business Admin can define one or more legal agreements and upload them to the platform. Once available in the platform, one or more legal agreements can be incorporated into a license definition.

To set up a legal agreement in the platform, the Business Admin completes the following steps:

• Uploads a legal agreement (an external file) as part of the Licenses wizard when setting up a license.
• Defines the agreement for purposes of UI display (name, description).

Once a legal agreement is defined as part of a license, the API Access wizard displays the agreement to any developer requesting API access with this license. The developer must accept the legal agreement as part of the API access request.

Licenses

The license is the top-level item where the customization dovetails into a clear specific offering to the app developer.

The license model is defined by the Business Admin. The API Admin completes the picture, relating the license to the API, by assigning scopes to specific operations.

When the app developer requests API access, the licensing choices are presented as part of the API Access wizard and the app developer simply selects the license most suitable to the unique scenario for that app.

Some points about licenses:

• A license can be for the Sandbox or Live implementation or both.
• Access to either the Sandbox or Live implementation can be set up to be auto approved or can require explicit approval on the part of the API Admin.
• A license can have Public or Private visibility. Note that even if a license is public, it could have scopes that are private. In this scenario, all users will see the parts of the API that are not part of the private scope, but visibility/access to operations and documentation that are part of a private scope are available only for users with the applicable licenses.
• A license can include one or more License Terms. For flexibility in setup, no license terms are required to create a license, although in practice a license is meaningless without license terms.

Visibility

There are two core visibility states for objects on the platform—Public, which means the object is visible to anyone who accesses the platform, and Private, which means that it is visible only to invited users (members of an invited group). API, Scope, License, App, and Group all have Public and Private visibility options.

The Public and Private visibility states work with the Licenses feature to give you very fine control over the visibility that you offer for your API. If your API is private, you control visibility by inviting groups of users to your API or by creating an API Scope Group and inviting individuals to it. If you have private licenses, you also determine which licenses are offered to which of these groups. Portions of your API that are mapped to private scopes are not even visible to developers who are members of a group invited to your API unless you specifically invite them with licenses that include the private scopes.

Since you can design your licenses in any way you want, you can allow whatever level of access you want to allow to a specific individual or group.

Let's say you want your API to be private, but you want to invite members of Group A to have read-only access and members of Group B to have full access. You can easily achieve this. Just invite both groups to access your API, then tailor the access of Group A to include only the license that you've defined for read-only access. Done.

Visibility for groups

When an API is using the Licenses feature, and the API admin invites a group to have visibility of the API, the API admin can also control the level of visibility that the group has by following the steps below.

Note: The API must be using the Licenses feature.

In the platform, go to the API. On the left, click Visibility and then click Groups. All the groups that have visibility to the API are listed. From this page the API admin can:

• Invite additional groups.
• Specify the licenses each group has visibility to: unrestricted access or specific access to one or more licenses defined for the API.

API documentation tags

If you want to limit the visibility of some parts of an API, so that some users don't see those operations, naturally you don't want those users to be able to view the corresponding API documentation.

When the API admin determines licenses for the API, the platform automatically restricts visibility of the API documentation to users who have the appropriate permissions. The API admin, or a delegate, designates which sections of the documentation are visible to which users by applying a set of tags to the API documentation

By applying the tags around the document content, it is easy to determine the licenses for which that part of the documentation is visible. If the viewing user has the applicable license, that user sees the documentation. If not, the content is not displayed.

Doc tags provide control of visibility at the file level and also at a more granular level by tagging specific content within a file. By combining both approaches, the API admin can define a documentation tagging strategy that's most efficient for the specific API.

An example is shown below.

<soa:showforlicense licenseNames="Gold Level">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="about_goldlicense.htm">About the Gold-Level License</a>.</p>
  </div>
</soa:showforlicense>

As an implementation example, let's say an API owner, Bill, wants to offer a Gold level license only to specific customers. It includes three additional operations as well as a higher QoS policy. The API documentation includes:

• One separate file for each operation
• One file covering the additional features offered at the Gold level
• One main index page that includes information about all the licenses the API offers, with a link to the documentation for each operation, each in a separate file

The API admin, Joe, uses the documentation feature to make the three files for the Gold operation, and the Gold overview file, visible to Gold license holders. It is hidden from all other users.

In the main index page, Joe tags the links to the four files containing Gold license content so that these links are visible to Gold customers.

All other content is tagged for the Silver license which is offered to all other customers, and also tagged for the Gold license. Gold customers see all; Silver customers do not see the Gold content.

For more information on implementing the document tagging feature, including instructions and examples, refer to API Documentation Visibility Tagging.

API access requests

The point at which an app developer requests access to an API is where both the API owner and the app developer customers reap the benefits of the Licenses feature.

Instead of black and white all-or-none access, the app developer can choose from the licenses that have been a) defined for the API and b) designated as visible to him/her, and can choose the license most applicable to the app's exact scenario—the operations that the app needs to have access to and the appropriate level of access (quality of service).

If the API includes subsets (scopes, packaged into licenses) that are only for a select audience, other developers will never even see those options or the associated documentation.

Each developer will see only what is available to him/her, and out of those choices will request API access with the most appropriate license.

As a final step in the process, if the licenses have been set up so that API access requests require manual approval by the API admin, when evaluating the API access request the API admin can further modify the API access level that is granted to the app.

Putting it together

Briefly, here are the high-level steps to implement this feature.

Prerequisites:

• QoS policies defined in Akana Policy Manager
• Legal agreements defined and uploaded

The Business Admin:

1. Defines scopes.
2. Defines licenses.
3. Lets the API admin know the scope and license definitions for API doc tagging.

The API Admin:

1. Adds API using the Add API wizard.
2. Turns on Licensing for the API (from the API Details page, choose Manage Licensing, then check Enable Licensing for API).
3. Maps operations to scopes.
4. Uploads tagged documentation.
5. Optionally, creates an API Scope Group and invites developers to the group, or invites an independent private or public group to the API.
6. Assigns one or more licenses to each group that is invited to the API.

The App Developer:

1. Browses the API documentation (depending on how the API is defined, the developer might be viewing a subset of the documentation).
2. Adds the app to the platform using the Add App wizard.
3. Initiates an API access request.
4. Chooses from the available licenses (if more than one is available) to complete the request.

Then the API Admin:

• (If access is not set to automatic upon request) Reviews API access request and modifies, approves, or rejects.

Use case examples

Here are some examples of how an API owner can use the Licenses feature to administer, strategize, and monetize an API.

Bronze, Silver, and Gold users

Let's say the owner of PQR API, Jerry, wants to offer three levels of access/service to users:

• Bronze Level—Unlimited free read-only access. Access is limited to the GET functions in the API. Auto approval, public visibility.
• Silver Level—$5 per month for up to 200 API calls. Full access to all operations. Auto approval, public visibility.
• Gold Level—$50 per month for up to 3000 API calls. Full access to all operations. Approval required, public visibility.

Note: As a variation on the above, the configuration could also offer a Metered License—for example, $0.10/transaction. Jerry could use the detailed auditing API usage logs and custom reports in the Akana API Platform and Policy Manager to compute the monthly bills.

Here's how to set up the bronze, silver, and gold level licensing example.

Define scopes: This scenario requires two categories of API access; read-only access (to GET operations, for Bronze) and full access (to all operations, for Silver and Gold). As part of this, the Business Admin defines two scopes, Read Only and Update. The Read Only scope is defined as a child to the Update scope.

Define licenses: Business Admin defines three licenses: Bronze, Silver, and Gold. These will be available for the app developer to choose from when requesting API access.

Enable licenses: API Admin enables Licenses on the API and sets the API to Private.

Map scopes: API Admin maps all GET operations to the read-only scope and also maps all operations to the Update scope.

Small and large customers plus development partner

Here is a scenario where you can use the Licenses feature to make some parts of your API visible only to a select group of users.

Let's say you have these three types of users:

• A small group of large customers. This is the main user group and brings in the most income.
• A large group of small customers. All these apps currently have fairly low usage levels.
• One specific large customer who is a key technology partner and has requested additional functionality for the API.

To accommodate these customer groups, the Business Admin first defines the following Scopes:

• Read-Only (GET operations only)
• Full Publish (all operations except those for beta testing)
• Beta (operations for beta testing)

Now the Business Admin defines the following Licenses:

• Orange: Read-only access at no charge. Some of the small customers will use this license.

  Maps to scope: Read-Only

• Green: Full access to most operations, limited cost, limited bandwidth. Small customers who need full functionality will use this license.

  Maps to scope: Full Publish

• Platinum: Full access to most operations, higher price, greater bandwidth. The large customers will use this license.

  Maps to scope: Full Publish (different QoS policy)

• Beta: Access to new operations for beta testing purposes. No cost, private visibility.

  Maps to scope: Beta

  The API Admin creates an API Scope Group for beta testing, invite the technology partner to the group, and make the Beta license visible to the group.

  The technical writer tags the API documentation so that the new operations are visible to those with a license that includes the Beta scope.

The technology partner can now choose API access with the Beta license and try out the new operations. The other customers continue to enjoy their normal level of service and are completely unaware that beta testing is occurring.

Flexible configuration of offerings

Let's say the API owner might want to offer access to one operation, at a rate of up to 10 transactions per second, for no charge, and the API has five operations. The Business Admin defines five licenses, A, B, C, D, and E, each including one scope, A, B, C, D, E, and each including the same QoS policy for 10/s.

Instead, perhaps the API owner wants to offer 10 transactions per second at no charge, but doesn't mind which operations are used as long as overall usage doesn't exceed 10. In this scenario, the Business Admin defines one license with five scopes and one QoS policy. The 10/s QoS policy then applies to all the scopes, combined.

It is easy to apply the same approach for monetization with higher consumption levels. As an API owner, you might want to define exactly how much you charge for traffic specifically to a high-volume endpoint. For other operations that are lower volume, exact numbers might not be significant as long as the overall package is fair. The flexibility allows you to package exactly what works best for you and for your app developer customers.

Licenses feature: end to end use case

For a complete end-to-end use case, including step-by-step instructions and illustrations for setting up an API and using the Licenses feature so that different users have visibility of different operations, see Use Case: Controlling API Documentation Visibility with Licenses.

License feature: user experience for the app developer

When an app developer requests API access, the API Access wizard steps him/her through the process.

The app developer:

1. Chooses the environment.
2. Chooses the most appropriate Quality of Service policy option.
3. Sees a list of licenses to choose from. These could be public licenses, or private licenses that the user has visibility of based on group membership.
4. If needed, clicks Show to view details about the license.
5. Accepts legal agreements if there are any.
6. Clicks Done, and the API access request is complete.