Documentation Tagging

This document provides an overview of the documentation tagging feature which is a key component of the Licenses feature. Tagging your documentation allows you to make sure that relevant content is exposed to the applicable audience.

This document is intended primarily for the API owner or designated individual who will be applying tags to the API documentation before it is uploaded to the portal. It includes information on tagging strategy and practical examples of how to apply the tags.

It includes the following sections:

• Overview of documentation tagging
• Managing visibility settings
• Visibility of API documentation
• Testing
• Documentation tagging strategy
• Tagging at the file level
• Tagging content within a file
• Making sure documentation Is visible

Overview of documentation tagging

The Licenses feature allows you to package your API into different licenses for different user groups. Whether your licenses offer access to the entire API or to defined subsets of your API operations, when you choose to offer licenses it opens the door to you granting customized access to custom user groups. By doing this, you are at the same time restricting access for users who are not members of the specified groups.

In some cases, you might also apply privacy at various levels. Privacy settings allow you to restrict visibility into certain areas of your API. You can make the entire API private so that it is visible only to invited users; but you can also define licenses or scopes to be private. For example, you might have a group of new operations that need to be tested, and you want to make these available to a beta partner without exposing them to your main customer base. You can do this by defining a private scope, assigning it to a private license, and inviting your beta partner to have visibility to the private license.

When you elect to use licenses, you must also tag your documentation to let the platform know which portions of your documentation set should be visible to which users, according to the user's visibility permissions to your API. If your documentation is not tagged, the basic default is as follows:

• Private API, public scopes: Content tagged for public scopes is visible to invited users (members of invited groups).
• Public API, public scopes: content tagged for public scopes is visible to all users.
• Private scopes: content tagged for private scopes is visible only to users specifically invited to have visibility of a license that includes the private scope.

Back to top

Managing visibility settings

You can limit visibility—that is, which users can see your API—by applying privacy settings at these levels:

• API

  The entire API can be marked as private. If the API is private, a user must be a member of an invited group, or of the private API group, to see the API. If an API is private but all the scopes are public, invited users can see all scopes and operations; if the scopes are private, no matter whether the API is public or private, only users who are specifically invited will see the licenses that include private scopes.

• License

  Whether the API is public or private, a license can be public or private. A public license is visible to those who have visibility of the API; if a license is private, specific permission is required.

• Scope

  Whether the API is public or private, a scope can be public or private. A public scope is visible to all who have visibility of the API; if a scope is private, a user must be invited to have visibility of a license that includes the scope.

The table below summarizes these privacy levels.

If an API is...	And a license is...	And a scope is...	API visibility/doc visibility (if tagged) is...
Public	Public	Public	Visible to all.
Public	Public	Private	Visible to all, except private scopes by invitation only.
Public	Private	Public	Visible to all, except private licenses by invitation only.
Public	Private	Private	Visible to all, except private licenses by invitation only.
Private	Public	Public	Visible only to users who are members of a Private API Group or invited group.
Private	Public	Private	Visible to invited users, except private scopes by invitation only.
Private	Private	Public	Visible to invited users, except private licenses by invitation only.
Private	Private	Private	Visible to invited users, except private licenses by invitation only.

Back to top

Visibility of API documentation

If you use the Licenses feature, it gives you a lot of flexibility regarding portions of your API that you show or hide to different audiences. From the API owner's perspective the basic process is essentially:

You determine how you want to package your API to offer it to different audiences. You can:

• Offer the entire API with different quality of service agreements and/or legal agreements.
• Subdivide the API by using the scope mapping feature to map individual operations to specific scopes. The Business Admin has already defined licenses and the scopes that are part of them, so you'll need to coordinate with the Business Admin to make sure your scope mapping results in the correct license offerings to your app developer audience.

A key point, though, is the fact that if you are using the License feature at all, you must tag your API documentation with the applicable tags so that the documentation is visible to the applicable users. Even if the API is public and the licenses are public, if you don't tag the documentation it will not be visible.

Back to top

Testing

We highly recommend that you test your API documentation to make sure it's visible to users with the appropriate licenses.

When you upload the API documentation, all the documentation should be visible to you since you are the API Admin and have full access rights. If there are any tagging errors, you might not know it unless you test.

Testing scenario

Let's say for example you have a public API and create a scenario using these three licenses:

• A Bronze license for limited view-only access (public)
• A Gold license for full access to your published API (public)
• A Beta license for access to your newest operations for beta testing (private)

Because the API is public, any user can request API access and choose between the Bronze and Gold licenses. Only invited users will see the Beta license. Your documentation must be appropriately tagged so that all users will see the documentation for the Bronze and Gold licenses and only Beta license holders will see the documentation for the part of your API you're releasing for those customers.

Test steps

Here are some test steps you could follow.

To test that the API documentation is tagged correctly:

1. Set up a test user.
2. Request production approval to the Bronze license.
3. View the documentation. You should be able to see the portions of your documentation that are tagged for Gold and Bronze licenses/scopes but not the content tagged for the Beta license/scope.
4. Now, as the API Admin, invite your test user to have visibility of the Beta license.
5. As the user, change your API access request to a request for the Beta license.
6. View the documentation. You should now be able to view the content for all three licenses.

Back to top

Documentation tagging strategy

There are two main aspects to the documentation tagging feature. When you understand both, you'll be able to design a strategy that best matches your unique scenario and is most efficient for you and appropriate for your audience. The two work together to give you fine control over the visibility of your API documentation. They are:

• Metadata.xml: file-based authorization; specifying audience at the file level. At the highest level, the metadata.xml file allows you to specify which of your documentation files, or groups of files, are visible to which users based on the API version and the licenses, scopes, or operations that the user is authorized to view. You must set up the applicable API Version ID in the metadata.xml file to ensure that your documentation visibility settings will work. For details about how to set up your metadata.xml file, see Tagging at the File Level below.
• Content tagging within a file; this is a more granular approach, allowing you to tag specific pieces of content within a file. The user's view of the file is personalized/customized based on the visibility access of the viewing user.

How doc tagging works

At runtime, the platform checks the settings on the files and/or content and verifies against the access rights of the viewing user. Where there is a match, content is displayed. Any content that doesn't match the viewer's rights is not displayed to the user.

A recommended approach is to separate out most of your content for different user groups by file. For example, you could have one file for each license you offer; or you could have one file for each operation.

The overview page would then lead in to the various types of content. In this file, you could use the more granular level of tagging by paragraphs, so that each user sees only the links to additional files that are viewable for that user. Other links would not be seen.

Any additional content that would need to be shared by different groups would also have to be tagged at the more granular level.

Note: If you are using the Licenses feature, and you have content that you want to display to all users, tag that content as visible for a specific public license, scope, or operation. If your API is public and a license is public, content tagged for that license will be visible to all users, even anonymous users (users who have not logged in). If you do not tag the content at all, it is not displayed to users at all.

Information design: tips

There are two key reasons to keep the information design of the documentation simple:

• If there are many paragraphs tagged for specific user subsets (whether by license, scope, or operation) it could get complicated to track which content is seen by which users. Particularly, you would need to make sure that both source and destination for any links are viewable by the same users. Otherwise, users might see a link but not have permission to follow the link—or, conversely, users might not see a link to a piece of content that they do actually have permission to see, and therefore cannot access viewable content.
• Tagging by paragraph requires more processing, since the platform must check permissions at many levels. A streamlined approach is more efficient on the processing side.

Back to top

Tagging at the file level

The top level of doc tagging is at the file level. Here you determine which files or groups of files are accessible to which users based on the user's visibility permissions.

You can specify visibility at the file level in three ways:

• By license
• By scope
• By operation

Tagging at the file level has several key advantages:

• It's simplest for you; you apply one tag for a whole file or set of files rather than tagging specific portions of individual files.
• It's the most secure type of tagging. Even a user who knows the URL to a file will not be able to access it.
• It requires the least amount of processing on the part of the platform.

The metadata.xml file

You set up tagging at the file level in a metadata.xml file that resides in your documentation folder. The file structure and options are shown below. You can use this example and customize it for your own licenses, scopes, or operations.

This file is appropriate for this scenario:

• Three licenses: Bronze, Gold, and Beta
• Three scopes: ReadOnly, FullScope, and Beta
• Five operations: getPayment is assigned to ReadOnly/Bronze, listPayments to Beta, the other three to FullScope/Gold
• Two API versions. Most files are for both API versions, but each version also has one file that's designated for that specific version. The index file is designated for the main version.

In the example below, variable content is shown in boldface.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<metadataconfig xmlns="http://soa.com/xsd/metadataconfig/1.0">
  <metadata>
    <APIVersionID xmlns="http://soa.com/xsd/api/1.0">apiversion10081.acmecorp</APIVersionID>
    <target>documents/index.html</target>
    <scopes>
      <scope name="ReadOnly"/>
    </scopes>
  </metadata>
  <metadata>
    <target>documents/m_addPayment.htm</target>
    <operations>
      <operation name="addPayment"/>
    </operations>
  </metadata>
  <metadata>
    <target>documents/m_modifyPayment.html</target>
    <operations>
      <operation name="modifyPayment"/>
    </operations>
  </metadata>
  <metadata>
    <target>documents/m_deletePayment.html</target>
    <operations>
      <operation name="deletePayment"/>
    </operations>
  </metadata>
  <metadata>
    <target>documents/m_getPayment.html</target>
    <operations>
      <operation name="getPayment"/>
    </operations>
  </metadata>
  <metadata>
    <target>documents/m_listPayments.html</target>
    <operations>
      <operation name="listPayments"/>
    </operations>
  </metadata>
  <metadata>
    <target>documents/scope_public_FullScope.html</target>
    <scopes>
      <scope name="FullScope"/>
    </scopes>
  </metadata>
  <metadata>
    <target>documents/scope_public_ReadOnly.html</target>
    <scopes>
      <scope name="ReadOnly"/>
    </scopes>
  </metadata>
  <metadata>
    <target>documents/scope_private_Beta.html</target>
    <scopes>
      <scope name="Beta"/>
    </scopes>
  </metadata>
  <metadata>
    <target>documents/license_public_bronze.html</target>
    <licenses>
      <license name="Bronze"/>
    </licenses>
  </metadata>
  <metadata>
    <target>documents/license_private_beta.html</target>
    <licenses>
      <license name="Beta"/>
    </licenses>
  </metadata>
  <metadata>
    <target>documents/license_public_gold.html</target>
    <licenses>
      <license name="Gold"/>
    </licenses>
  </metadata>
  <metadata>
    <APIVersionID xmlns="http://soa.com/xsd/api/1.0">apiversion10093.acmecorp</APIVersionID>
    <target>documents/user_invited.html</target>
    <roles>
      <role name="InvitedUser"/>
    </roles>
  </metadata>
</metadataconfig>

Structure of a metadata.xml file entry

Each entry in the metadata.xml file conforms to the same structure.

The sample file below has a single entry. The outer tag, <metadataconfig>, is shown in bold. Within this tag you can add as many <metadata> tags as you need.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<metadataconfig xmlns="http://soa.com/xsd/metadataconfig/1.0">
  <metadata>
    <APIVersionID xmlns="http://soa.com/xsd/api/1.0">apiversion11622.acmecorp</APIVersionID>
    <target>documents/index.html</target>
    <roles>
      <role name="InvitedUser"/>
    </roles>
  </metadata>

...

</metadataconfig>

Each <metadata> tag has, or can have, the following optional or required components:

• Optional: a reference to a specific API version ID. If not specified, <metadata> tags apply to all versions of the API.
• A <target> node indicating the filename. In the example above, the filename is index.html.
• A <roles>, <operations>, <scopes>, or <licenses> node that lists the specific applicable roles, operations, scopes, or licenses determining permission to view the specific object named in the <target> node.
• One or more individual role, operation, scope, or license names. Operations are as specified for the API; scopes and licenses are as specified by the Business Admin.

Naming and referencing your doc tags

It's important to make sure your doc tag names exactly match the values set up elsewhere. If there are differences in case, the tags might not work as expected, depending on your environment. It's best to be exact and consistent with regard to spelling and case.

Make sure:

• You use the license, scope, and operation names exactly as they are set up in the user interface.
• You use the license, scope, and operation names completely consistently within your metadata.xml file and your documentation tags.
• You represent file names in the metadata.xml file exactly as they appear in your documentation fileset.

Back to top

Tagging content within a file

Setting up the metadata.xml file covers the broad strokes of your documentation tagging, defining which files are accessible to which audiences.

There will also be at least one or two instances where you'll need to designate content within one file as having limited availability depending on visibility access rights.

For example, let's say you have two new operations in beta testing and want to make those available only to your beta testing partners. You define the beta scope and license, you write the documentation for those operations, and you set up the metadata.xml file so that the beta documentation is available only to those with the beta license.

When your beta user goes to your documentation, how will the user access the private files? There must be some lead-in that is available to all users, and from there you can offer links to private content.

The content tagging approach lets you tag specific content within an individual file, so that some portions of the file are visible to users and other portions of the file are not displayed. A common scenario is to customize the main index page, creating a separate section for each user group (based on visibility rights). Sections of content tagged for users with specific visibility rights are invisible to unauthorized users. Each user only sees content that he/she is authorized to view, and from there can click through to other files containing authorized content.

The platform displays content by checking the permissions of the viewing user for licenses, scopes, and operations and comparing the viewer's permissions with the licenses, scopes, and operations specified in the tagged content.

Where the tags match the user's permission, the content is displayed. If a tag specifies a license, scope, or operation to which the viewer does not have access, the content is not displayed.

Tagging within a file: requirements

To use the content-specific tagging feature, you'll need to do two things:

• Include specific information in the top part of the file, in the <html> and <head> tags
• Apply tags to individual content sections

Tagging: all files

Below is an example of the opening <html> tag and entire <head> tag of a sample HTML file, showing where the additional entries are placed to implement the documentation tagging feature. Relevant entries are highlighted.

<html lang="en" xmlns:soa="http://soa.com">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />

<title>API Documentation Overview</title>

<link href="../../../../resources/style/reset.css" rel="stylesheet" type="text/css" />
<link href="../../../../resources/style/base.css" rel="stylesheet" type="text/css" />
<link href="../../../style/document.css" rel="stylesheet" type="text/css" />

<script language="javascript" src="/resources/thirdparty/jquery/jquery-1.8.0.min.js"  type="text/javascript"></script>
<script language="javascript" src="/ui/apps/acmecorp/123/resources/javascript/dynamic_docs.js"  
type="text/javascript"></script>

</head>

If you are implementing this feature, you have three main choices of how you can tag your documentation for visibility:

• Tagging by scope
• Tagging by license
• Tagging by operation

You can also tag content to be viewable only by a user who is logged in, or only by an anonymous user.

In each scenario, you'll need to enclose the relevant content within specific code tags as outlined in the sections below.

Note: In the tags, make sure that the scope, license, or operation name is exactly the same as it is in the user interface, including case. Case differences might not be an issue, but it's best to be exact.

Example: tagging by scope

If you want to restrict visibility of certain pieces of content within a file so that the content can only be seen by users with visibility into a specific scope, use the tags below.

Remember to also specify in the metadata.xml file that the applicable file is accessible to users with visibility of the same scope. If you don't, users will see the link and be able to click the link but will not have permission to view the target file.

The platform automatically checks access rights, and makes the content visible to users who have visibility into licenses that include the applicable scope.

In the example below, variable content is highlighted.

<soa:showforscope scopeNames="ScopeName">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="ContentRelatingToScope.html">Link to file with content relating to ScopeName</a>.</p>
  </div>
</soa:showforscope>

Example: Tagging by license: public

If you want to restrict visibility of certain pieces of content within a file so that the content can only be seen by users with visibility into a specific license, use the tags below.

Remember to also specify in the metadata.xml file that the applicable file is accessible to users with visibility of the same license. If you don't, users will see the link and be able to click the link but will not have permission to view the target file.

In the example below, the API is private but the license (LicenseName_Public) is public. All users who have been invited to the API will see the content below. Users who have not been invited will not see the API at all, and will not be able to access the content.

<soa:showforlicense licenseNames="LicenseName_Public">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="ContentRelatingToPublicLicense.html">Link to file with content relating to LicenseName (a public license)</a>.</p>
  </div>
</soa:showforlicense>

Example: Tagging by license: private

In the example below, the API is private and the license (LicenseName_Private) is also private. To see this content, users must be invited to the API but also must be invited to this specific license. Even members of groups that are invited to the API will not see the content unless specifically invited to see this license.

Remember to also specify in the metadata.xml file that the applicable file is accessible to users with visibility of the same license. If you don't, users will see the link and be able to click the link but will not have permission to view the target file.

<soa:showforlicense licenseNames="LicenseName_Private">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="ContentRelatingToPrivateLicense.html">Link to file with content relating to LicenseName (a private license)</a>.</p>
  </div>
</soa:showforlicense>

Example: Tagging by operation

If you want to restrict visibility of certain pieces of content within a file so that the content can only be seen by users with visibility into a specific operation, use the tags below.

Remember to also specify in the metadata.xml file that the applicable file is accessible to users with visibility of the same operation. If you don't, users will see the link and be able to click the link but will not have permission to view the target file.

The platform automatically checks access rights, and makes the content accessible to users who have visibility into licenses that include scopes with the applicable operations.

<soa:showforlicense operationNames="addPayment">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="addPayment.html">Link to file with content relating to the addPayment operation</a>.</p>
  </div>
</soa:showforlicense>

Example: Tagging by role

You can restrict visibility of a specific piece of content so that it can only be seen by users with a specific role. The valid roles are:

• InvitedUser: for a Private API, a user who has been invited to have visibility into the API and has accepted (generally via an invitation to a group that has visibility into the API)
• Admin: the API admin

In the example below, all invited users for this version of this private API will see the index.html page.

<metadata>
  <APIVersionID xmlns="http://soa.com/xsd/api/1.0">apiversion10093.acmecorp</APIVersionID>
  <target>documents/index.html</target>
  <roles>
    <role name="InvitedUser"/>
  </roles>
</metadata>

Example: Tagging for multiple items

You can restrict visibility of a specific piece of content so that it can only be seen by users with a specific combination of more than one license, more than one scope, or more than one operation.

Multiple items must all be of the same type. For example, you cannot set up a single entry to combine one scope and one license. The entries would have to be separate.

In the example below, only users who have visibility into both scopes will see the designated content.

Multiple scopes

<soa:showforscope scopeNames="public-scope-1, private-scope-2">
<div class="soa-ui-cm-dynamic-docs">
  <a href="twoscopes.html">twoscopes.html</a><br><br>
</div>
</soa:showforscope>

Example: showforanonymoususer

If there is some content in your documentation that you want to share broadly to readers who are not logged in, you can apply the showforanonymoususer tag, as shown below. For example, you might use this for a page encouraging users to sign up for the platform and use your API. You'll need to add a link on the documentation TOC for this file, since it wouldn't be accessible via your documentation index page. Users who are logged in do not see this content.

<soa:showforanonymoususer>
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="user_new.html">Learn more about our API and the platform!</a></p>
  </div>
</soa:showforanonymoususer>

Example: showforloggedinuser

If there is some content in your documentation that you want to share with all platform users who are logged in, you can apply the showforloggedinuser tag, as shown below.

<soa:showforloggedinuser>
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="user_loggedin.html">Learn more about our API!</a></p>
  </div>
</soa:showforloggedinuser>

Back to top

Making sure documentation is visible

It's very important to make sure that your documentation is visible to the appropriate audiences. Once you've tagged your files and uploaded them, test.

Make absolutely sure that your documentation index page will be accessible. Even if most of your API is by invitation only, there should ideally be some general information that's available to as many users as possible. A broadly available index page is an opportunity to tell people about your API.

We recommend that you tag the index page with the following:

• Private API: Use the InvitedUser tag to make the index page available to all users who are invited to your API.
• Public API: Define at least one public scope, and use it to make the index page available to all users.

Note: If there are any overlapping conditions, the user has to meet all the conditions for the content to be displayed to that user.

Correctly applied, documentation tagging will ensure that each piece of your API documentation content is available for its specific target audience, as defined by you, and for nobody else. No matter how private you want your documentation to be, or how broadly available you want to make it, you can accomplish your goals by correctly tagging your content for valid licenses, scopes, and operations and testing thoroughly.

Back to top