This document provides an overview of the Licenses feature and how it can be implemented to manage API access, define different levels of access along with appropriate service level agreements, and monetize an API.
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 topic includes the following sections:
The platform’s Licenses feature gives you complete control over the level of access you offer for your API. The feature is designed so that you can exactly customize your access offerings, including:
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.
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:
The new operations are assigned to a scope, specifically for the large customer, which has a visibility setting of Private. All other operations are assigned to a second scope with a visibility of Public. Two licenses are defined. One, for the large customer, offers access to both scopes; 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 a Private API Group and invites the large customer. The other customers, not being invited to the private group, are unaware of these new operations. The documentation is tagged with visibility tags for each license, so that the portion of your API documentation that’s visible to a specific app developer matches the developer’s visibility into your API as defined by you.
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.
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 now 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.
You want 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:
The API Admin assigns all GET operations to the Read scope and assigns all the remaining operations to the Update scope.
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. Note that all Business Admins are automatically API Admins for all APIs, so the same individual 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, you can monetize API operations that serve data based on service profiles, or monetize operations that execute transactions based on transaction volume and response time. You can also define a completely new set of licenses and leave the older ones in place only to support existing customers.
This section provides an overview of the feature in action, including:
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:
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.
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.
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 (Private API Groups or independent groups) so they have visibility into the API.
API Admins are responsible for tagging API documentation with visibility tags, uploading API documentation, and approving the access requests from the 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.
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 Licenses feature uses the following components:
Scopes, Terms, QoS Policies, and Legal Agreements make up the hierarchy of a License definition. Visibility, API access requests, and API documentation tags are not specifically part of this hierarchy but are key components.
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 which 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.
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 into the parent scope automatically has visibility to the descendent scopes. Similarly, if an app has parent 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.
Looking at permissions from another perspective, if an app, user, or group has access to a descendent scope, it can be assumed that the app, user, or group also has access to the parent scope, up to the top scope level.
As an example of scope implementation—the Business Admin might create two scopes, Read Only and Update. By defining these logical groupings, the Business Admin enables the API Admin to assign applicable operations to those two scopes, and thus package the API into license offerings.
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 to production and/or sandbox environments, whether anonymous access is allowed to production and/or sandbox environments, 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.
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 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:
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 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 SOA Software 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.
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:
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: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.
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:
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 allow 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. 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.
When you are using the Licenses feature, and you invite a Group to have visibility to your API, you can also control the level of visibility that the group has.
Note: You must first make sure the API is using the Licenses feature. From the API’s Board, click Edit and then make sure the Use Licenses checkbox is checked.
In the platform, go to the Board for 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 you can:
If you want to limit the visibility of some parts of your API, so that some of your users don’t see those operations, naturally you don’t want those users to be able to view the corresponding API documentation.
The platform allows you to limit the visibility of your API documentation by applying a set of tags to your HTML. By applying the tags around your document content, you specify 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.
You can control visibility at the file level, or at a more granular level by tagging specific content within a file.
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 you offer a Gold level license only to specific customers. It includes three additional operations as well as a higher QoS policy. Your documentation includes:
You use the documentation feature to hide the three files for the Gold operation, and the Gold overview file, from all other users.
In the main index page, you tag 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.
The point at which an app developer requests access to your API is where both you and your 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.
Briefly, here are the high-level steps to implement this feature.
Here are some examples of how an API owner can use the Licenses feature to administer, strategize, and monetize an API.
Let’s say you want to offer three levels of access/service to your users:
Note: As a variation on the above, your configuration could also offer a Metered License—for example, $0.10/transaction. You could use the detailed auditing API usage logs and custom reports in Community Manager and Policy Manager to compute the monthly bills.
Here’s how you set up the bronze, silver, and gold level licensing example.
Define scopes: You want to offer 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.
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:
To accommodate these customer groups, you first define the following Scopes:
Now you define the following Licenses:
Maps to scope: Read-Only
Maps to scope: Full Publish
Maps to scope: Full Publish (different QoS policy)
Maps to scope: Beta
You create a Private API Group for beta testing, invite your technology partner to the group, and make the Beta license visible to the group.
You tag your API documentation so that the new operations are visible to those with a license that includes the Beta scope.
Your technology partner can now choose API access with the Beta license and try out your new operations. Your other customers continue to enjoy their normal level of service and are completely unaware that beta testing is occurring.
Perhaps you want to offer access to one operation, at a rate of up to 10 transactions per second, for no charge, and you have 5 operations. You could define 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.
Let’s say instead that you want to offer 10 transactions per second at no charge, but you don’t mind which operations are used as long as overall usage doesn’t exceed 10. In this scenario you could define one license with five scopes and one QoS policy. The 10/s QoS policy then applies to all the scopes, combined.
You can apply the same approach for monetization with higher consumption levels. 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.
When an app developer requests API access, the API Access wizard steps him/her through the process.
The app developer: