API Documentation Visibility Tagging

Learn how to tag your API documentation to control visibility of documentation files.

Note: The customization samples ZIP file, downloadable in platform versions 2020.2.0 and later, includes working examples of doc tagging. If you're on an earlier version and want a copy of the file, contact Technical Support. For more information, see How do I get the sample files for the doc tagging example? below.

Table of Contents

Doc Tagging General Information:

Doc Tagging By File:

Doc Tagging By Content:

Streamlining Content-Based Doc Tagging:

Testing and Finalizing:

Doc Tagging General Information:

How do I get the sample files for the doc tagging example?

In version 2020.2.0 and later, there is a customization ZIP file, available for download within the Community Manager developer portal by any Site Admin. This file includes examples of doc tagging that you can unzip and use to test doc tags, see how they work, and then apply them to your API documentation.

For information about downloading the ZIP file, see How do I get the customization samples? (2020.2.0 and later).

If you are not a Site Admin, and would like a copy of the ZIP file, ask your Administrator.

If you are on an earlier version of the platform, ask your Akana representative to contact Technical Support to get a copy of the file.

Within the customization ZIP file, look at the readme file in the root folder for information on the examples available. There are differences between versions. In 2020.2.0 the doc tagging examples are in these folders:

  1. simple_licenses_and_scopes—Walks you through a use case, with detailed instructions for setting up users, scopes, licenses, groups, apps, and assignments, to test out the doc tagging functionality.

    Includes readme.md and a test Swagger file.

  2. advanced_licenses_and_scopes—Walks you through a different use case, with detailed instructions for all setup actions.

    Includes a set of test files for Hermosa theme and another for Bonita, that you can use to modify, upload, and test, including a sample metadata.xml file (for Hermosa theme).

What types of content can I use documentation tagging for?

Documentation tagging allows you to control who will see your content.

Here are two examples of types of content you can use documentation tagging for on the platform:

  • Site documentation. The documentation might include instructions for different user groups, such as app developers and API admins. If you don't want your app developers to see the API Admin documentation, you can apply file-based tagging. For an example, see How do I use file-based tagging to filter by user role?
  • API documentation. You can use doc tagging to limit parts of your API documentation for users with visibility of a specific license, scope, or even operation; you can also tag documentation to be visible to specific types of users, logged-in users, or anonymous users.

How do I control visibility of API documentation files?

If an API uses licenses, visibility of API documentation files is restricted to users who are authorized, based on their access to licenses, scopes, or operations and the way that the documentation is tagged. The platform offers a series of visibility filters that you can use to control the display of applicable API documentation files, or portions of content within individual files, to authorized users. If the API uses licenses, API documentation tagging must be used.

When API documentation is tagged appropriately, the platform displays documentation to users who are authorized, based on membership of one or more groups that have visibility of the API. Other users do not see the documentation.

Tagging your API documentation, in combination with the licenses feature, 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:

  1. You determine how you want to package your API to offer it to different audiences. For example, 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 must define the 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 strategy results in the correct license offerings to your app developer audience.
  2. You apply scopes to your operations and licenses to your API.
  3. You apply tags to your API documentation as covered in the topics below.

Note: If your API uses licenses 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. At minimum, set up a metadata.xml file with one or more entries that make all your files visible to all users.

Multi-Level Privacy

In some cases, you might also apply privacy at various levels. Privacy settings allow you to restrict visibility of 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.

What are the visibility rules for API documentation?

The visibility rules for API documentation are shown in the table below.

API Visibility Use Licenses? Documentation Visibility
Public No Documentation is visible to all users, including anonymous users.
Public Yes Documentation must be tagged for the appropriate licenses. If not tagged, documentation is not visible, even if the API is public. If appropriately tagged, documentation associated with public scopes is visible to all users, including anonymous users. Documentation associated with private scopes is only visible to users who have visibility to the private scopes.
Registered Users No Documentation is visible to all users who are logged in.
Registered Users Yes Documentation must be tagged for the appropriate licenses. If appropriately tagged, documentation associated with public scopes is visible to all users who are logged in. Documentation associated with private scopes is only visible to users who have visibility to the private scopes.
Private No Documents are visible only to API Admins, Business Admins, and users who are members of a group that has visibility of the API (API Scope Group or invited independent group).
Private Yes API documentation mapped to a private license or scope is available only to users who have visibility of the applicable license or a license that includes the applicable scope. Visibility is based on group membership. Note that the API documentation must be tagged according to the tagging rules as explained in How do I control visibility of API documentation files? below. If an API uses licenses, whatever the visibility setting is for the API, documentation tagging must be used.

Where do I apply API visibility settings?

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

  • API

    You can mark the entire API as private. If the API is private, a user must be a member of an invited group or an API Scope Group, or be an API Admin, in order 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 what the visibility setting is for the API, only users who are specifically invited will see the licenses that include private scopes.

  • License

    No matter what the visibility setting is for the API, 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

    No matter what the visibility setting is for the API, 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 an API Scope 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.

What are the different ways I can tag API documentation?

There are two main ways that you can tag documentation. 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. You can use them in combination; the two approaches work together to give you fine control over the visibility of your API documentation.

They are:

  • File-based tagging
  • Content-based tagging

File-based tagging

File-based tagging is the recommended approach for most content. An additional file in the documents folder, metadata.xml, controls which files are accessible to which users. This file-based authorization 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, or based on the user's role. For tagging of API documentation, you must set up the applicable API Version ID in the metadata.xml file to ensure that your documentation visibility settings will work.

Content-based tagging

Content-based tagging allows you to tag specific pieces of content within a file, to control who can see that piece of content. This more granular approach gives you fine control over the visibility of your content. What a viewing user sees is personalized/customized based on the user's access rights and permissions. To use this feature, you'll need to add some lines of code in the <head> tag of your file, as explained below.

This approach can get complex, so it's best to keep it to a minimum; for example, you could use content-based tagging in your main index file and file-based tagging for the rest of your files.

How does documentation tagging work?

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.

Note: A full set of linked files and setup instructions is also available, as a ZIP file that you can customize, upload, and test. To get a copy of the doc tagging ZIP file, contact Technical Support.

What is file-based doc tagging and how does it work?

File-based tagging is the recommended approach for most content. An additional file in the documents folder, metadata.xml, controls which files are accessible to which users.

In your documents directory, set up the metadata.xml file with permission settings for your API documentation files, using special tags. You can set permissions:

  • For individual files
  • For specific file types
  • For folders that should have restricted visibility

The settings in the metadata.xml file determine not only visibility but also authorization. If file restrictions are set up in the metadata.xml file, a user cannot access those files even if the user has the URL for the file.

For instructions on how to set up the metadata.xml file, see How do I use the metadata.xml file for file-based tagging?

What is content-based doc tagging and how does it work?

With content-based tagging, you apply special tags to specific pieces of content within a file. At runtime, visibility rules are applied to each section of content according to the tags you set up.

We recommend that you use this approach judiciously. Permissions vary by user, and documentation projects often include links between files, so a simple tagging approach is most efficient. Refer to the examples below for some ideas.

To implement content-based tagging, you'll need to reference the jquery.js and dynamic_docs.js files within the <head> tag of your HTML files. For an example, see I want to use content-based tagging: how do I set up my file? below.

Note: Unlike file-based authorization, content-based visibility filters are implemented on the browser side only. This feature is considered a "personalization" feature rather than authorization.

How do I name and reference my doc tags?

It's important to make sure your doc tag names exactly match the values set up elsewhere. This is equally true for file-based or content-based tagging.

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 file set.

File-based tagging is simplest; content-based tagging can get complex, so it's best to keep it to a minimum.

The approach we recommend is to use content-based tagging in your main index file and file-based tagging for the rest of your files. This is an efficient combination that allows you to take advantage of the features of both approaches while keeping things simple and easy to maintain.

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

  • If there are many paragraphs tagged for specific user subsets (whether by license, scope, or operation) it can get complicated to track which content is seen by which users. Particularly, you must make sure that both source and destination for any links are viewable by the same users. Otherwise, you might run into one of these issues:
    • Users can see a link but do not have permission to follow the link.
    • Users do not see a link to a piece of content that they do actually have permission to see, and therefore cannot access content that is relevant to them.
  • 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.

Tagging the index page

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 then tag the index page for that scope in the metadata.xml file, so that it will be available to all users.

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

Tagging by user group

Another 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.

My API uses licenses, but I just want my documentation to be visible to everyone. What's the easiest way to set that up?

If your API uses licenses, and you have content that you want to display to all users, tag your 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, it is not displayed to users at all.

To implement this, you'll need to have a public license and apply it to all your operations.

Create the metadata.xml file in your documents directory, create a single entry as shown below, and substitute your actual license name.

Example #1: Public API using licenses, public license assigned to all operations, target documentation available to all authorized users

The example below defines a rule that all .html files in the documents folder for this API version are only visible to invited users. Note that if you have other types of files, you'll need to list those also, in an additional <target> node, as shown in Example #3.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<metadataconfig xmlns="http://soa.com/xsd/metadataconfig/1.0">
  <metadata>
    <target>documents/*\.html</target>
    <licenses>
      <license name="mypubliclicensename}">
      </license>
    </licenses>
  </metadata>
</metadataconfig>

Example #2: Private API using licenses, documentation visible to all invited users (HTML files)

If your API is private, but you don't care about restricting access to API documentation, you can use the <roles> tag to make all the documentation visible to invited users.

The example below defines a rule that all .html files in the documents folder for this API are visible to invited users.

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

Example #3: Private API using licenses, documentation visible to all invited users (multiple file types)

The example below defines a rule that makes multiple documentation files for the API visible to invited users. In this example, the API documentation includes several file types. Each is listed separately in an additional <target> node.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<metadataconfig xmlns="http://soa.com/xsd/metadataconfig/1.0">
  <metadata>
    <target>documents/*\.html</target>
    <target>documents/*\.jpg</target>
    <target>documents/*\.pdf</target>
    <roles>
      <role name="InvitedUser"/>
    </roles>
  </metadata>
</metadataconfig>

Doc Tagging By File

How do I use the metadata.xml file for file-based tagging?

You can control the visibility of API documentation and downloadable files by creating a metadata.xml file that includes one or more regular expressions and uploading it to the /documents folder for the API (API > Documentation > File Manager). The regular expressions specify which files can be seen, via tagging, for one or more of the following:

Note: If your API uses licenses, you must include the metadata.xml file with appropriate tagging. If you don't specify a metadata.xml file with permissions to your content, or if you include a metadata.xml file but don't add the information about your files, your users will not see your documentation, other than the properties file and any legal agreements. This includes a custom CSS file or any other assets associated with your documentation. This is always true when the API uses licenses, even if the API is public.

Apply the desired filters to the complete documentation set. You can also add version-specific entries (See How do I use file-based tagging to filter by API version? below).

In the metadata.xml file, include each filter that you want to apply, enclosed in <metadata> </metadata> tags. Examples of each are given in the sections below.

The filters are executed in sequential order. In the file, organize your filters in this order:

  1. First, use filters that apply to all documents.
  2. Next, use API version filters.

For information about how you can get the customization example files for doctagging, including metadata.xml, see How do I get the sample files for the doc tagging example? above. Example #1 includes metadata.xml.

What are the advantages of file-based tagging?

Tagging at the file level has several key advantages:

  • It's simplest for you; you apply one tag to 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.

What does the metadata.xml file look like?

The metadata.xml file has the following key elements:

For information about how you can get the customization example files for doctagging, including metadata.xml, see How do I get the sample files for the doc tagging example? above. Example #1 includes metadata.xml.

Some examples of the full metadata.xml file are shown below.

Sample metadata.xml file #1

The example below shows a simple metadata.xml file with one API version, 0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp; one operation, addPayment; one scope, fullscope-public; and one license, Gold. There is one file within each tag.

In this scenario, users will only see the link to a specific file if they have permission to the applicable API version, scope, operation, or license. Users who do not have the applicable visibility permissions will not see the links (and would not be able to access the files even if they had the URLs).

Note: In setting up your metadata.xml file, make sure you get the names of referenced objects, such as license, scope, or file names, exactly right. Make sure the case matches.

<?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">0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp</APIVersionID>
    <target>documents/index.html</target>
    <roles>
      <role name="InvitedUser"/>
    </roles>
  </metadata>
  <metadata>
    <target>documents/addPayment.html</target>
    <operations>
      <operation name="addPayment"/>
    </operations>
  </metadata>
  <metadata>
    <target>documents/fullscope-public.html</target>
    <scopes>
      <scope name="fullscope-public"/>
    </scopes>
  </metadata>
  <metadata>
    <target>documents/license_public_gold.html</target>
    <licenses>
      <license name="Gold"/>
    </licenses>
  </metadata>
</metadataconfig>

Sample metadata.xml file #2

The sample file below 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.

You can use this example and customize it for your own licenses, scopes, or operations.

<?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">0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp</APIVersionID>
    <target>documents/index.html</target>
    <scopes>
      <scope name="ReadOnly"/>
    </scopes>
  </metadata>
  <metadata>
    <target>documents/m_addPayment.html</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">0157f427-0b07-4ae6-9ade-26f4ef3bcc71</APIVersionID>
    <target>documents/user_invited.html</target>
    <roles>
      <role name="InvitedUser"/>
    </roles>
  </metadata>
</metadataconfig>

What does an entry in the metadata.xml file look like?

Each entry in the metadata.xml file has the following elements:

  • Optional: an <APIVersionID> tag that limits the rule to a specific version of the API. If an API version is not specified, <metadata> tags apply to all versions of the API.
  • Required: a <target> node that states which files are affected by the rule. There can be multiple <target> nodes but there must be at least one.
  • Required: A node that specifies the visibility rules that are applied to the file. This can be one of several types of nodes; for example, limiting visibility by role, license, scope, or operation. Operations are as specified for the API; scopes and licenses are as specified by the Business Admin. There can be more than one, but they must be of the same type.

The sample file below has a single entry.

In the sample <metadata> node below, visibility is limited by role. Only users with the role of InvitedUser will see the index.html file specified in the <target> node.

<metadata>
  <APIVersionID xmlns="http://soa.com/xsd/api/1.0">0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp</APIVersionID>
  <target>documents/index.html</target>
  <roles>
    <role name="InvitedUser"/>
  </roles>
</metadata>

How do I use file-based tagging to define the API version a file applies to?

If you have a file that includes content for a specific API version, you can apply the <APIVersionID> tag.

This tag is the primary way that the Community Manager developer portal controls which API documents apply to which version. In Hermosa Theme, when a user chooses to view documentation for a specific API version, the platform uses the API version tag to filter visibility so that the user only sees documentation that's applicable to the specified API version.

An example is shown below. To see this line in context, see Sample metadata.xml file #1.

<APIVersionID xmlns="http://soa.com/xsd/api/1.0">0157f427-0b07-4ae6-9ade-26f4ef3bcc71.tenantid</APIVersionID>

How do I use file-based tagging to filter by license?

The <licenses> filter in the metadata.xml file allows you to specify one or more target documents and one or more license names. Users must have visibility of all specified licenses in order to have visibility of the specified documents.

An example is shown below.

<metadata>
  <target>documents/license1.html</target>
  <licenses>
    <license name="license1">
    </license>
  </licenses>
</metadata>

How do I use file-based tagging to filter by scope?

The <scopes> filter in the metadata.xml file allows you to specify one or more target documents and one or more scope names. Users must have visibility of all specified scopes (via licenses that they have visibility of) in order to have visibility of the specified documents. In the Community Manager developer portal, the API Admin maps scopes to API operations using the information set up in the Manage Licensing page, accessed via the API's Details page.

An example is shown below.

<metadata>
  <target>documents/scope1.html</target>
  <target>documents/scope2.html</target>
  <scopes>
    <scope name="scope1">
    </scope>
    <scope name="scope2">
    </scope>
  </scopes>
</metadata>

How do I use file-based tagging to filter by operation?

The <operations> filter in the metadata.xml file allows you to specify one or more target documents and one or more operation names. Users must have visibility of all specified operations (via licenses that they have visibility of, that include scopes the operations are mapped to) in order to have visibility of the specified document. The API Admin maps scopes to API operations using the information set up in the Manage Licensing page, accessed via the API's Details page.

An example is shown below.

<metadata>
  <target>documents/operation2.html</target>
  <operations>
    <operation name="operation2">
    </operation>
  </operations>
</metadata>

For information on how to specify multiple target documents or multiple resources, see How do I use file-based tagging to assign the same filter to more than one file type? below.

How do I use file-based tagging to assign the same filter to more than one file type?

Within a specific <metadata> tag, you can specify multiple <target> nodes. The rules specified in the <metadata> tag are applied to all files specified in one or more <target> nodes.

In the example below, users must have visibility of all specified operations (via licenses that they have visibility of, that include scopes the operations are mapped to) in order to have visibility of either of the specified documents.

<metadata>
  <target>documents/operation1.html</target>
  <target>documents/operation2.html</target>
  <operations>
    <operation name="operation1">
    </operation>
    <operation name="operation2">
    </operation>
  </operations>
</metadata>

How do I use file-based tagging to filter by user role?

You can restrict visibility of a specific piece of content by specifying the entire documentation file in the metadata.xml file so that it can only be seen by users with a specific login status. The valid roles are:

  • InvitedUser: for a Private API, a user who has been invited to have visibility of the API and has accepted (generally via an invitation to a group that has visibility of the API)
  • Admin: the administrator of the referenced object. Can be the admin for an app, app version, API, API version, or group.
  • SiteAdmin: the administrator of the tenant that owns the resource.
  • SystemAdmin: used only for access root workflow.
  • BusinessAdmin. For objects that do not belong to a business, the tenant's business scope will be applied

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">0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp</APIVersionID>
  <target>documents/index.html</target>
  <roles>
    <role name="InvitedUser"/>
  </roles>
</metadata>

Multiple roles: visibility for either role

When using file-based tagging to restrict visibility by user role, you can also tag content for multiple roles. If the viewing user has one of the specified roles, the content is visible. An example is shown below.

<metadata>
  <APIVersionID xmlns="http://soa.com/xsd/api/1.0">0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp</APIVersionID>
  <target>documents/operation1.html</target>
  <roles>
    <role name="SiteAdmin">
    </role>
    <role name="ApiAdmin">
    </role>
  </roles>
</metadata>

How do I use file-based tagging to filter by file extension?

In the metadata.xml file, you can specify a filtering rule that applies to all files of a specific file type by specifying a regular expression in the <target> node.

For example, if you want to define a specific rule to apply to all .html files in the /documents folder, you could define the <target> node as follows:

<target>.*\.html</target>

Example: HTML file extension, one role

The example below defines a rule that all .html files in the documents folder for this API version are only visible to invited users:

<metadata>
  <target>documents/*\.html</target>
  <roles>
    <role name="InvitedUser"/>
  </roles>
</metadata>

Example: HTML file extension, multiple roles

The example below defines a rule that all .html files in the documents folder for this API version are only visible to users with either of two roles:

<metadata>
  <target>documents/*\.html</target>
  <roles>
    <role name="SiteAdmin">
    </role>
    <role name="ApiAdmin">
    </role>
  </roles>
</metadata>

Example: Microsoft Word files

The example below defines a rule that applies to all Microsoft Word .docx files in the /documents folder:

<target>.*\.docx</target>

Example: Multiple <target> nodes

You can also specify multiple <target> filters. To specify a rule that applies to all .html and .jpg files in the /documents folder, you could include two <target> nodes:

<target>.*\.html</target>
<target>.*\.jpg</target>

How do I use file-based tagging to limit visibility of a specific file?

You can filter visibility of a specific file by specifying the filename in the <target> node. For example, you might want to define a filtering rule that applies to a specific PDF file, sample.pdf, so that it's visible only to users with a certain license. To do this you would specify the filename in the <target> node and the license in the <license> node, as shown below.

<metadata>
  <target>apis/sample.pdf</target>
  <licenses>
    <license name="license1">
    </license>
  </licenses>
</metadata>

How do I use file-based tagging to filter by API version?

In addition to applying filters to all API documentation, you can further filter documentation for a specific version of the API by using the <api:APIVersionID> filter.

You configure this filter by extracting the API Version ID plus tenant name (for example, 0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp) from the API documentation URL. It's the ID that's after /versions/ in the path. In the example below, it's the second ID in the path.

Example URL: 

https://{hostname}/api/69afe821-0660-4c78-a593-809535d6223f.acmepaymentscorp/versions/0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp/documents

If you want to include an API version filter, place it after the <metadata> tag, before the <target> node.

Refer to the examples in What does the metadata.xml file look like? above.

Example: specific API version, all HTM files, specific license

The example below limits access to all .html files for the specified API version so that those files are only visible to users with visibility of the Gold license:

<metadata>
  <api:APIVersionID>0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp</api:APIVersionID>
  <target>.*\.html</target>
  <licenses>
    <license name="Gold"/>
  </licenses>
</metadata>

Example: specific API version, specific file, specific operations

The example below limits visibility of all PDF files for the specified version to users with visibility of either of the specified operations:

<metadata>
  <api:APIVersionID>0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp</api:APIVersionID>
  <target>apis/sample.html</target>
  <operations>
    <operation name="operation1">
    </operation>
    <operation name="operation2">
    </operation>
  </operations>
</metadata>

When I'm doing file-based tagging, can I use operators?

The metadata.xml file does not support the use of operators.

When using file-based tagging to restrict visibility by user role, you can tag content for multiple roles. If the viewing user has one of the specified roles, the content is visible.

The same thing applies to tagging for multiple licenses, scopes, or operations.

The metadata.xml file does not support the and operator. The default behavior is always or.

For an example of tagging for multiple roles, see Multiple roles: visibility for either role. For an example of tagging for multiple operations, see Example: specific API version, specific file, specific operations.

When I'm doing file-based tagging, what regular expressions can I use in metadata.xml?

In some cases, you can use a regular expression to add flexibility in terms of the file set that a rule in the metadata.xml file applies to.

The table below shows regular expressions you can use.

This regular expression... Does this...
*\

Applies the rule to all files matching the stated context. For example:

api12345/*\.pdf

The above applies the rule to all PDF files in the api12345 folder

For an example, see Example: HTML file extension, one role.

Doc Tagging By Content

When should I use doc tagging by content?

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

It's best to organize the bulk of your content using file-based tagging, so that entire files are visible or hidden based on a user's visibility settings. However, there will be at least one or two instances where you'll need to designate content within one file as being visible only to users with access to the applicable licenses, scopes, or operations. This is where doc tagging by content comes in.

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.
  • Assign the beta scope to your new operations.
  • Write the documentation for those operations.
  • Set up the metadata.xml file so that the beta documentation is available only to those with the beta license.
  • Set up your main index file with a link to the file for the new operations, tagged for the new scope or license.

The lead-in to your API documentation content will need to accommodate all possible users, with some way to branch off to private content that's accessible only to a restricted audience, as in the above example.

The content-based tagging approach lets you tag specific content within an individual file, so that individual portions of the file are visible only to specific audiences.

A common, and recommended, approach 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.

I want to use content-based tagging. How do I set up my file?

You can use the content-based tagging feature to show or hide sections of a specific document based on the visibility access rights of the viewing user. To use this feature you'll need to do these things:

What tags are available for content-based doc tagging?

The following tags are supported for doc tagging within a specific file:

In each scenario, you'll need to enclose the relevant content within specific code tags as outlined in How do I tag a section of content? 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.

Tags are mutually exclusive and cannot be nested.

How do I set up the <html> tag in my file?

To the HTML tag at the very top of the file, add xmlns:soa="http://soa.com. Your entry should look similar to the following: 

<html lang="en" xmlns:soa="http://soa.com>

How do I set up the <head> tag in my file?

Within the <head> tag, after the <title> tag, add the following lines, replacing the {resource.version} variable with your own unique value:

<link rel="stylesheet" type="text/css" href="/resources/style/reset.css"/>  
<link rel="stylesheet" type="text/css" href="/resources/style/base.css"/> 
<script language="javascript" src="/ui/apps/atmosphere/{resource.version}/resources/uiframework/jquery/jquery.js"
  type="text/javascript"></script>
<script language="javascript" src="/ui/apps/atmosphere/{resource.version}/resources/console/javascript/dynamic_docs.js"
  type="text/javascript"></script>

Note: when you reference reset.css, as in the above example, you must also define styles in your custom css. For more information, see What are reset.css and base.css and why would I use them?

For information about the {resource.version} variable and what value to use, see What is the {resource.version} variable and why is it important?

If you need to add compatibility for users of IE9 and below, you can include a conditional comment to an additional stylesheet. For details and an example, see How do I make sure my API documentation is rendered correctly for users of Internet Explorer 9 and below?

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.

<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 rel="stylesheet" type="text/css" href="/resources/style/reset.css"/>  
<link rel="stylesheet" type="text/css" href="/resources/style/base.css"/> 
<script language="javascript" src="/ui/apps/atmosphere/123456/resources/uiframework/jquery/jquery.js"
  type="text/javascript"></script>
<script language="javascript" src="/ui/apps/atmosphere/123456/resources/console/javascript/dynamic_docs.js"
  type="text/javascript"></script>
</head>

What is the {resource.version} variable and why is it important?

If you want to use content-based tagging in a documentation file, the doc file must reference these two JavaScript files:

<link rel="stylesheet" type="text/css" href="/resources/style/reset.css"/>  
<link rel="stylesheet" type="text/css" href="/resources/style/base.css"/> 
<script language="javascript" src="/ui/apps/atmosphere/{resource.version}/resources/uiframework/jquery/jquery.js"
  type="text/javascript"></script>
<script language="javascript" src="/ui/apps/atmosphere/{resource.version}/resources/console/javascript/dynamic_docs.js"
  type="text/javascript"></script>

In the file paths, you can use whatever value you want to use in the /{resource.version}/ part of the path. For example, you could use the platform version (recommended) or your API version or API doc version.

The importance of this value is in controlling the version of the dynamic_docs.js file that is served to your users. This file is cached by the browser, for efficiency. However, if there is a new version with increased capabilities, and you use those new capabilities in a new version of your documentation, when your users are viewing the file you'll want the browser to use the new version of the dynamic_docs.js file, not an earlier, cached version.

In this scenario, all you need to do is update the value of the {resource.version} variable in the file path. Changing the value ensures that when a user accesses your documentation, the browser will reference the latest version of the file.

If you see in the release notes for a new version that there are updates to the dynamic documentation capabilities, it's best to update the value of your {resource.version} variable to make sure you and your users get the full functionality of the new features.

How do I tag a specific section of content?

To use content-based tagging, you must include specific information in the <html> tag at the top of the file, as covered in How do I set up the <html> tag in my file? and in the <head> tag, as covered in How do I set up the <head> tag in my file?

Once that's done, you can apply the tags to individual sections of content.

To use the content-specific tagging feature, apply tags to individual content sections. Within the section, wrap the content in a <div> tag and apply this class: soa-ui-cm-dynamic-docs.

For information on which tags are available, see What tags are available for content-based doc tagging? For information on a specific type of tag, and examples, refer to the applicable topic.

The example below is generic to demonstrate the basic structure of a tag.

<soa:showfor_{tagname} ...>
<div class="soa-ui-cm-dynamic-docs">
<!-- Tagged section goes here-->
</div>
</soa:showfor_{tagname}>

How do I use content-based tagging to restrict visibility by license?

To restrict visibility of certain pieces of content within a documentation file, so that the content can only be seen by users with visibility of a specific license, specify the license names in the soa:showforlicense tag.

To specify multiple licenses, separate them with commas.

If the tagged content is a link to another file, remember to also specify in the metadata.xml file that the destination 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 documentation tag, use a <div> tag with the soa-ui-cm-dynamic-docs tag assigned to it. Refer to the examples below.

The platform automatically checks access rights, and makes the content accessible to users who have visibility of the applicable license.

Note: If you want to restrict documentation visibility by license, you must assign scopes to licenses and also assign scopes to the API.

Example 1: one license

In the example below, when an app developer has visibility of the Gold license, based on the license's privacy settings and the developer's visibility access, the developer can view the link to a separate file containing information about this license.

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

Example 2: tagging by license, private API, public license

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_Public (a public license)</a>.</p>
  </div>
</soa:showforlicense>

Example 3: tagging by license, private API, private license

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 destination 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_Private (a private license)</a>.</p>
  </div>
</soa:showforlicense>

How do I use content-based tagging to restrict visibility by scope?

To restrict visibility of certain pieces of content within a documentation file, so that the content can only be seen by users with visibility of a specific scope, specify the scope names in the showforscope tag.

To specify multiple scopes, separate them with commas.

If the tagged content is a link to another file, remember to also specify in the metadata.xml file that the destination 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 of licenses that include the applicable scope.

Note: If you want to restrict documentation visibility by scopes, you must assign scopes to the API. To assign scopes to your API, in API > Details > from the drop-down on the right, Manage Licensing. See What is scope mapping and how do I set it up? For the most security, be sure to assign at least one scope to each operation. If an operation doesn't have a scope assigned, no specific license is needed to access that operation.

In the documentation tag, use a <div> tag with the soa-ui-cm-dynamic-docs tag assigned to it. Refer to the examples below.

Example 1: one scope

In the example below, when an app developer has visibility of the specified scope, ScopeName, the developer can view the link to the file containing information about the scope.

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

Example 2: two scopes

In the example below, when an app developer has visibility of either of the specified public scopes, the developer can view the link to a separate file containing information about these scopes.

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

How do I use content-based tagging to restrict visibility by operation?

To restrict visibility of certain pieces of content within a documentation file, so that the content can only be seen by users with visibility of a specific operation, specify the operation name in the showforoperation tag.

To specify multiple operations, separate them with commas.

If the tagged content is a link to another file, remember to also specify in the metadata.xml file that the destination 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.

In the documentation tag, use a <div> tag with the soa-ui-cm-dynamic-docs tag assigned to it. Refer to the examples below.

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

Note: To restrict documentation visibility by operation, scopes must also be assigned to the API. To assign scopes to your API, in API > Details > Manage Licensing, check the Enable Licensing for API box, and then select either API-Wide Mapping or Operation-Specific Mapping. Assign scopes to operations and save. For the most security, be sure to assign at least one scope to each operation. If an operation doesn't have a scope assigned, and the API is public, no specific license is needed to access that operation. If the API is private and an operation has no scope, no users can access that operation.

Then, in the API documentation HTML file, configure the tags as follows, adding one or more operation names separated by commas.

An example is shown below.

<soa:showforoperation operationNames="addPayment">
  <div class="soa-ui-cm-dynamic-docs">
      <p><a href="addPayment.html">Documentation for addPayment operation</a></p>
  </div>
</soa:showforoperation>

How do I use content-based tagging to restrict visibility by role?

The examples below illustrate several scenarios you can use to tag documentation to be visible to users with a specific role or multiple roles.

Note: When tagging by role, if the tag references multiple roles, by default a user with just one of the roles can see the content. However, you can use the AND operator to specify that the user must have all specified roles in order to see the content, as illustrated in the examples below.

Valid role values for the roleNames parameter are:

  • SiteAdmin
  • BusinessAdmin
  • Admin (a user who is both API Admin and Business Admin)
  • ApiAdmin

You can also tag for multiple roles.

Example 1: Site Admin

In the example below, the specified file is visible only to users with the role of Site Admin.

<soa:showforrole roleNames="SiteAdmin">
  <div class="soa-ui-cm-dynamic-docs">
    <a href="site-admin.html">site-admin.html</a>
  </div>
</soa:showforrole>

Example 2: Business Admin

In the example below, the specified file is visible only to users with the role of Business Admin.

<soa:showforrole roleNames="BusinessAdmin">
  <div class="soa-ui-cm-dynamic-docs">
    <a href="business-admin.html">business-admin.html</a>
  </div>
</soa:showforrole>

Example 3: Admin (user must be either API Admin or Business Admin)

In the example below, the specified file is visible only to users with the Admin role. This role includes both API Admin and Business Admin. Therefore, the file is visible to users with the role of either API Admin or Business Admin.

<soa:showforrole roleNames="Admin">
  <div class="soa-ui-cm-dynamic-docs">
    <a href="api-admin.html">api-admin.html</a>
  </div>
</soa:showforrole>

Example 4: Site Admin or Business Admin: user must have either role

In the example below, the specified file is visible only to users with the role of either Site Admin or Business Admin. This is the same result as the example above, but is accomplished by specifying multiple roles. This approach could also be used for specifying a different combination of roles; for example, API Admin or Business Admin.

Note: When tagging by role, if multiple roles are specified, by default the content is available to users who have one of the referenced roles.

<soa:showforrole roleNames="SiteAdmin, BusinessAdmin">
  <div class="soa-ui-cm-dynamic-docs">
    <a href="site-admin-or-business-admin.html">site-admin-or-business-admin.html</a>
  </div>
</soa:showforrole>

Example 5: Admin (user must be either API Admin or Business Admin)

In the example below, the specified file is visible only to users with the role of either API Admin or Business Admin.

<soa:showforrole roleNames="Admin">
  <div class="soa-ui-cm-dynamic-docs">
    <a href="api-admin.html">api-admin.html</a>
  </div>
</soa:showforrole>

Example 6: Multiple roles; user must have both roles

In the example below, the specified file is visible only to users with the role of both Site Admin and Business Admin. The and operator (case does not matter) causes both roles to be required.

<soa:showforrole roleNames="SiteAdmin, BusinessAdmin" condition="and">
  <div class="soa-ui-cm-dynamic-docs">
    <a href="site-admin-and-business-admin.html">site-admin-and-business-admin.html</a>
  </div>
</soa:showforrole>

Example 7: Multiple pieces of tagged content within a file

The example below shows five pieces of content. Each type of admin (API, Business, Site) will see the one piece of content that's tagged for that role. If content is tagged for either of two roles (OR), and the user has one of the roles, the user will see it. If content is tagged for users who have both roles (AND), only users with both roles will see it.

<soa:showforrole roleNames="ApiAdmin">
  <div class="soa-ui-cm-dynamic-docs">
    <h3>API Admin</h3>
    <p>Important information for the API Admin.</p>
  </div>
</soa:showforrole>
<soa:showforrole roleNames="BusinessAdmin">
  <div class="soa-ui-cm-dynamic-docs">
    <h3>Business Admin</h3>
    <p>Important information for the Business Admin.</p>
  </div>
</soa:showforrole>
<soa:showforrole roleNames="SiteAdmin">
  <div class="soa-ui-cm-dynamic-docs">
    <h3>Site Admin</h3>
    <p>Important information for the Site Admin.</p>
  </div>
</soa:showforrole>
<soa:showforrole roleNames="SiteAdmin, BusinessAdmin" condition="and">
  <div class="soa-ui-cm-dynamic-docs">
    <h3>Business Admin AND Site Admin</h3>
    <p>Important information for any user who is Business Admin and also a Site Admin.</p>
  </div>
</soa:showforrole>
<soa:showforrole roleNames="SiteAdmin, BusinessAdmin">
  <div class="soa-ui-cm-dynamic-docs">
    <h3>Site Admin OR Business Admin</h3>
    <p>Important information for all users who are either Business Admin or Site Admin.</p>
    </div>
  </soa:showforrole>

Example 8: Sample File

In the customization ZIP file (see How do I get the sample files for the doc tagging example? above) you will find a working example showing content tagging for each role. The example files only work within the platform, because the supporting files are needed, but you can:

  • Upload the example files to the Community Manager developer portal and test the files to see how the tagging works.
  • Use the example files externally as a guide in coding your content, and then upload and test.

How do I use content-based tagging to make content visible only to anonymous users?

If there is some content in your documentation that you want to share specifically with users who are not logged in, you can apply the showforanonymoususer tag.

Some examples of how you might use this:

  • For marketing material.
  • For a special signup offer, 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.

An example is shown below.

<soa:showforanonymoususer>
  <div class="soa-ui-cm-dynamic-docs">
    <p>Information about our API and the platform!</p>
  </div>
</soa:showforanonymoususer>

If the tagged content is a link, remember to include it in the metadata.xml file, tagged with a public license or scope so that it is accessible to all users.

How do I use content-based tagging to make content visible only to users who are logged in?

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.

In the example below, only users who are logged in will see this line of content within a file.

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

When I'm using content-based tagging, can I use multiple tags?

When you're using content-based tagging, you can specify multiple entries of the same type (licenses, scopes, or operations) and separate them with a comma.

This restricts 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 of both scopes will see the designated content.

Example: Multiple scopes

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

When I'm doing content-based tagging, what operators can I use in my tags?

In most cases, with content tags, if you provide multiple values (separated by commas) the default behavior is or. This means that if the viewing user has visibility of one of the specified resources, the user can see the content. The exception to this is the soa:showforscope tag. For specifics, refer to the table below.

Tag Default operator Supports the "and" operator?
soa:showforlicense Or No
soa:showforscope And Yes, plus it is the default. The user must have visibility access to all the specified scopes in order to see the content.
soa:showforoperation Or No
soa:showforrole Or Yes. For this tag, the default value is or, but the and operator is also supported. If and is used, the viewing user must have all roles in order to have visibility of the content. for an example, see Example 6: Multiple roles; user must have both roles.
showforanonymoususer Or No
soa:showforloggedinuser Or No
soa:showforoperation Or No

Streamlining Content-Based Doc Tagging:

How can I simplify content-based doc tagging updates using the replacements.js file?

If you have a lot of tags on your documentation set, and something changes, you might have many updates to make. For example:

  • You might have a new license, or change a license name. Perhaps you have a new version of your Gold license, and you call it UltraGold, but you want users of the new license to see the new content.

Alternatively, you might have some customization in place that might affect how you tag your documentation. For example:

  • You might have a custom role. Perhaps you set up a custom role, SeniorAdmin, that encompasses both Site Admin and Business Admin roles.

The platform's documentation tagging feature includes a facility that you can use to help automate updates to your documentation. It's a JavaScript file, replacements.js, which you can customize to your implementation by performing the following steps:

  • In your doc tagging, instead of using the actual license, scope, operation, or role names, use placeholder variables.
  • In the replacements.js file, specify the values the platform will use for the placeholder variables.
  • In your documentation files, load replacements.js by means of a <script> tag in the <head> tag, before loading the dynamic_docs.js file.

Note: the processing of this file includes up to two levels of replacement. So, for example, you can map one variable to two or more variables. On the first pass, the single variable is replaced by the two variables; on the second pass, each of the two variables is replaced by the actual values. If two passes are not needed, the platform only does one (or none, if no variables are used).

Below is an example of a replacements.js file, which you can use to build your own. It includes:

  • At the top, a namespace declaration,
  • On each line, name-value pairs:
    • Name: a variable name which you can use in your doc tag, preceded by the namespace value. The replacements.js file looks for this value in your files, and replaces it with the second value.
    • Value: the value that's substituted. It can be the actual name of a scope, license, operation, or role, or it can be another variable which the platform will replace with actual values on a second pass through the documentation.
// only 2 levels for replacement processing like
// siteAdminCommaBusinessAdmin: "{MYAPP.siteAdmin}, {MYAPP.businessAdmin}" are supported.
// It is best to create a namespace such as MYAPP
window.MYAPP = {
  "mySampleAPIVersionId" : "changeMe(APIVersionID)",
  "siteAdmin" : "SiteAdmin",
  "businessAdmin" : "BusinessAdmin",
  "siteAdminCommaBusinessAdmin" : "{MYAPP.siteAdmin}, {MYAPP.businessAdmin}",
  "admin" : "Admin",
  "publicScope1" : "public-scope-1",
  "publicScope2" : "public-scope-1",
  "publicScope1CommaPublicScope2" : "public-scope-1, public-scope-1",
  "privateScope1" : "private-scope-1",
  "privateScope2" : "private-scope-2",
  "privateScope1CommaprivateScope2" : "private-scope-1, private-scope-2",
  "publicLicense1" : "public-license-1",
  "privateLicense1" : "private-license-1",
  "operationTargeted" : "operation-targeted"
}

In each line of the above, the first value is the name of a license, scope, operation, or role, that you might use in your doc tagging. The second value is a placeholder variable that you use in the documentation to designate that license, scope, operation, or role.

For information on the APIVersionID variable in the above, see How do I implement version-specific API documentation in Simple Dev theme?

Tip: It's best to create a namespace for the variables, as shown in the default example above, and then use it in all the names for your variables. For example, in the variable {ACMEPC.myscopename}, ACMEPC is the namespace, which would have to be defined at the top of the file as in the MYAPP example above (window.MYAPP = ). Using a namespace will ensure there's no naming collision between any variable names that might already be in use elsewhere in the platform.

Below are some examples of how you can use this file to automate your doc tagging updates.

Example 1: One change instead of many

Let's say you have many instances in your documentation files where there is content tagged for the GoldLicense. By setting up the below entry in your replacements.js file, if the license name changes, all you need to do is change the entry on the left in the file. You don't need to update any of the tags in your documentation files.

window.ACMEPC = {
  "goldLicense" : "Gold",
  ...
}

In this example, the tag in your documentation file would look like the below:

<soa:showforlicense licenseNames="{ACMEPC.goldLicense}">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="goldlicense.html">About the Gold License</a></p>
  </div>
</soa:showforlicense>

Note: You must also include a <script> tag in the head of the above HTML file; otherwise, the variables will not be replaced with the actual values. See How do I implement the replacements.js file? below.

Example 2: One variable for multiple values: licenses

Let's say you want to create a single tag that will give visibility permission for two licenses, Gold and Silver.

You can define variables for each license, and in addition a variable that encompasses both licenses, as follows: 

window.ACMEPC = {
  "goldLicense" : "Gold",
  "silverLicense" : "Silver",
  "goldAndSilverLicenses" : "{ACMEPC.goldLicense}, {ACMEPC.silverLicense}",
  ...
}

Your documentation tag might look like this:

<soa:showforlicense licenseNames="{ACMEPC.goldAndSilverLicenses}">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="license_goldsilver.html">Information for holders of multiple licenses</a></p>
  </div>
</soa:showforlicense>

On the first pass, the script would replace the variable like this:

<soa:showforlicense licenseNames="{ACMEPC.goldLicense}, {ACMEPC.silverLicense}">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="license_goldsilver.html">Information for holders of multiple licenses</a></p>
  </div>
</soa:showforlicense>

On the second pass, the script would replace the variable like this:

<soa:showforlicense licenseNames="Gold, Silver">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="license_goldsilver.html">Information for holders of multiple licenses</a></p>
  </div>
</soa:showforlicense>

With this approach, if you want to add a third license to the definition, you can change one line in the replacements.js file and your change is effected throughout the documentation set. Otherwise, you'd have to find every instance where documentation is tagged for two licenses and add the third. It's more work, and more possibility for error.

Example 3: One variable for multiple values: roles

Let's say you want to create a role for internal users. Site Admin and Business Admins are internal users; but the definition of this term might change, either to add API Admins or to remove Site Admins.

You can define a variable that encompasses these multiple roles, as follows: 

window.ACMEPC = {
  "siteAdmin" : "SiteAdmin",
  "businessAdmin" : "BusinessAdmin",
  "InternalUsers" : "{ACMEPC.siteAdmin}, {ACMEPC.businessAdmin}",
  ...
}

Your documentation tag might look like this:

<soa:showforrole roleNames="{ACMEPC.InternalUsers}">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="internal_users.html">Information for internal users only</a></p>
  </div>
</soa:showforrole>

On the first pass, the script would replace the variable like this:

<soa:showforrole roleNames="{ACMEPC.siteAdmin}, {ACMEPC.businessAdmin}">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="internal_users.html">Information for internal users only</a></p>
  </div>
</soa:showforrole>

On the second pass, the script would replace the variable like this:

<soa:showforrole roleNames="siteAdmin, businessAdmin">
  <div class="soa-ui-cm-dynamic-docs">
    <p><a href="internal_users.html">Information for internal users only</a></p>
  </div>
</soa:showforrole>

With this approach, if the definition of internal users changes, you can change one line in the replacements.js file and your change is effected throughout the documentation set.

How do I implement the replacements.js file?

If you're using a replacements.js file to automate maintenance of your doc tags, you'll need to load it with a <script> tag in the <head> tag of your HTML files, making sure you load it before the dynamic_docs.js file.

Below is an example of what the <head> tag of one of your documentation files might look like.

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <title>About the addPayment Operation</title>
  <link rel="stylesheet" type="text/css" href="/resources/style/reset.css"/> 
  <link rel="stylesheet" type="text/css" href="/resources/style/base.css"/> 
  <!--[if lte IE 9]>
  <link rel="stylesheet" href="/resources/style/ie.css">
  <![endif]-->
  <script language="javascript" src="/ui/apps/atmosphere/123/resources/uiframework/jquery/jquery.js"
  type="text/javascript"></script>
  <!-- load replacements.js before dynamic_docs.js -->
  <script language="javascript" src="./replacements.js"
  type="text/javascript"></script>
  <script language="javascript" src="/ui/apps/atmosphere/123/resources/console/javascript/dynamic_docs.js"
  type="text/javascript"></script>
</head>

Notes:

Where do I store the replacements.js file?

If you're using a replacements.js file to automate maintenance of your doc tags, upload the file to the main documents directory for your API doc.

How do I implement version-specific API documentation in Simple Dev theme?

You can support version-specific API documentation in Simple Dev theme by using the apiVersionId attribute in your content-based doc tagging.

The value of the attribute is defined in the replacements.js file, and your documentation HTML file must reference the replacements.js file in the <head> tag. For information and instructions, see How can I simplify content-based doc tagging updates using the replacements.js file?

By default, if an API has multiple versions, the latest version is the default version.

In Hermosa Theme, the user chooses the API, chooses the version, and then views the documentation. The platform applies the user's API version selection, filtering out the documentation by version. If the user doesn't choose a different version, the user sees the latest version, since it is the default.

In Simple Dev theme, this is not the case. There is no way for the platform to determine which API version the user is interested in. Therefore, to implement version-specific documentation in Simple Dev theme, you can use the API Version attribute in your content-based doc tags.

There are some content-based doc tags for which API version isn't relevant; for example, showforanonymoususer and showforloggedinuser. However, it is relevant for the following tags:

  • showforlicense
  • showforscope
  • showforoperation
  • showforrole

By tagging sections of your content with the apiVersionId attribute, you identify which sections of text should be shown for which API version.

The example below shows a tag that includes the apiVersionId attribute.

<soa:showforscope scopeNames="{ACMEPC.publicScope1}" apiVersionId="{ACMEPC.mySampleAPIVersionId}">
  <div class="soa-ui-cm-dynamic-docs">
    <a href="public-scope-1.html">public-scope-1.html</a>
  </div>
</soa:showforscope>

If you are not sure what the API version ID is for your version, you can easily get it from viewing the documentation in Hermosa Theme. See below.

To get the API ID and/or API version ID

  1. Log in to Hermosa Theme and go to the API.
  2. From the Versions drop-down at the top right, choose the version you want.
  3. Look at the URL. It will be something like the below:

    http://{hostname}/acmepaymentscorp/#/api/8d45ec68-5b0c-4ed5-87ec-c236f7aa8073.acmepaymentscorp/versions/4966a17a-8376-4086-bbe2-37fe8cf2cbf1.acmepaymentscorp/details

    The above example follows the structure given below: after /api/ is the APIID, then /versions/, and then the APIVersionID.

    http://{hostname}/#/api/{APIID}/versions/{APIVersionID}/details

  4. Copy the URL, and extract the API ID and/or API version ID.

Testing and Finalizing:

How do I test my API documentation tagging?

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, operations, and roles, and testing thoroughly.

It's very important to make sure the visibility is working as expected.

Here are some suggestions for testing your doc tagging:

Basic testing steps (before upload)

After you've finished tagging, test your documentation by performing the following checks:

  • Verify that the following are properly configured in all applicable HTML files:
    • <html> tag
    • <head> tag
    • <div> tags
    • {resource.version} variable
    • Visibility tags
  • Verify that the metadata.xml file is complete and that all of the following are correct:
    • Paths
    • Filenames
    • Referenced resource names (such as scopes and licenses)
  • If applicable, make sure that the API version is correctly specified. When you go to your API in the platform, the API version is in the URL path, after /versions/ in the path. It is in the format {uniqueid}.{tenant}. For example, 0157f427-0b07-4ae6-9ade-26f4ef3bcc71.acmepaymentscorp.
  • Verify that links to tagged sections are also tagged.
  • Verify that the scope and operation names you specified in the visibility tags are valid. In the Community Manager developer portal, scopes are mapped to operations on the Manage Licensing > Edit API Scope page.
  • Verify that the license names you specified in the visibility tags are available to your app developer audience via the API Access Wizard. To do this you can create a new app and submit an API Access Request by selecting Access at the top right of the API > Overview page.

Once you've completed the above steps, and any other testing steps you can think of, it's time to upload your files. See How do I upload my API documentation files?

Once you've uploaded, it's best to do further testing. See below.

Role-based testing (after upload)

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.

Once your API documentation is in place, it's best to test from the perspective of several users with different roles, or with visibility of different licenses, scopes, or operations, according to the tags you've used.

You'll want to make sure of two things, both very important:

  • That the API documentation is being displayed correctly to users who have the appropriate visibility rights.
  • That the API documentation is not being displayed to users who do not have the appropriate visibility rights.

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 create several test user accounts and request API access using various scenarios that will illustrate visibility and restricted visibility of API documentation in the API > Documentation section.

Sample testing scenario: overview

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 to those customers.

Sample testing scenario: test steps

In this sample testing scenario, below are some test steps you could follow.

To test that the API documentation is tagged correctly

  1. Set up a test user.
  2. Request API Access to the Live implementation with 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.

How do I control the documentation Table of Contents?

If you've selected a set of files to display in the documentation Table of Contents in the left navigation bar, in the API > Documentation section of the platform, the content is displayed dynamically based on the filters specified for all API documentation or for a specified API version.

For more information about working with the API documentation Table of Contents, refer to these topics in the Content Guidelines documentation: