Documentation Maintenance

Add / maintain API documentation and restrict visibility of documentation files.

Note: For more information about API documentation tagging, see Documentation Tagging

Table of Contents

1. What is the API documentation maintenance process?
2. Who can update API documentation content?
3. How do I add API documentation?
4. Can I link to API documentation on a different site?
5. What are the content guidelines for API documentation?
6. What are the visibility rules for API documentation?
7. How do I control visibility of API documentation files?
8. How do I upload my API documentation files?

What is the API documentation maintenance process?

All API documentation must be developed and maintained outside of the platform in your own HTML editor. Once your HTML content is ready you can upload it to the site.

If you add a new API version, you can update the existing documentation or create an entirely different set of documents. By default, all documentation files reside in the same folder. Here are a couple of approaches you could take to maintain files from different versions within the same folder structure:

• Use unique names for new files. For example, if you have two versions, with some files shared between versions and some files different for each version, you could name the unique files operationname_v1.htm, operationname_v2.htm, and so on. You could have one main index page that links to files for each version, or you could have a separate index page for each version.
• Use version-specific subfolders. For example, you could store version-specific files in v1 and v2 subfolders and keep shared files in the main documentation folder. In this scenario, you would need to have at least one file for each version in the main folder that would reference the version-specific files in the subfolders, or a single index page providing access to both versions.

For more detailed information about working with API documentation files, see Content Development Guidelines.

Back to top

Who can update API documentation content?

API documentation can be updated by:

• An API Admin for the API. This could be the person who set up the API on the platform or any other person who is a member of the API Admin team.
• A Business Admin

Back to top

How do I add API documentation?

You can add documentation for your API to the API > Documents section in two ways:

• By uploading content using the platform File Explorer.
• By using the Swagger documentation tool that is integrated with the platform.

For details, see Content Development Guidelines.

Back to top

Can I link to API documentation on a different site?

Yes. If you already have a website established for your API and/or your documentation, you can upload a file with some introductory text and a link to your website.

Remember to use the "target="_blank" attribute on the link so that the documentation site opens in a new window rather than replacing the platform user interface. For details, see Content Development Guidelines.

Back to top

What are the content guidelines for API documentation?

The platform provides a detailed set of content development guidelines for API documentation, including publishing, editing, styles, content organization, file upload, testing, and updating. For details, see Content Development Guidelines.

Back to top

What are the visibility rules for API documentation?

The following visibility rules apply for API documentation:

• APIs that are designated as Public and do not use licenses: Documentation is visible to all users (including anonymous users).
• APIs that are designated as Public and use licenses: Documentation must be tagged for the appropriate licenses. If appropriately tagged, documentation associated with public scopes is visible to all users. Documentation associated with private scopes is only visible to users who have visibility to the private scopes.
• APIs that are designated as Private but do not use licenses: Documents are visible only to API Admins, Business Admins, and users who are members of a group that has visibility into the API (Private API Group or invited independent group).
• APIs that are designated as Private and use licenses: API documentation mapped to a private license or scope is available only to users who have visibility into 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, whether the API is public or private, documentation tagging must be used.

Back to top

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 can be used to display 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.

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.

When a user who has full or partial visibility to an API selects the Documents menu link in the APIs section to view the documentation, the user sees the designated portion of the API documentation based on permissions, as determined by group membership and the group's visibility of the API. Content for all other licenses is hidden.

When using this feature, make sure that all links associated with documentation sections being filtered are also tagged accordingly. If there are visible links to hidden content, from the user's perspective the links will appear to be broken.

There are two approaches to tagging of documentation:

• File-based: In your documents directory, set up the metadata.xml file to match your installation. In this file you can specify files, file types, or folders that have restricted visibility.

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

  File-based tagging is the recommended approach for most content.

  For instructions on how to set up the metadata.xml file, see File-based tagging: Using the metadata.xml file below.

• Content-based: This is tagging at a more granular level, by applying tags to specific pieces of content within a file.

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

  Content-based tagging is controlled by referencing the jquery-1.8.0.min.js and dynamic_docs.js files within the <head> tag of your HTML files. See below for an example.

  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.

Activities relating to documentation tagging and visibility include:

• File-based tagging: using the metadata.xml file
• Setting up the documentation Table of Contents
• Content-based tagging: using documentation tags
• Using multiple tags
• Uploading your documentation files

File-based tagging: using the metadata.xml file

You can control the visibility of API documentation and downloadable files in the API > Documents folder by creating a metadata.xml file that includes one or more regular expressions that specify which files can be seen, via tagging, for one or more of the following:

• License
• Scope
• Operation
• Document type (file extension)
• File
• API version

If you do not specify a metadata.xml file with permissions to your content, your users will not see your documentation. This is always true when the API uses licenses, even if the API is public.

To apply filters, apply the desired filters to the complete documentation set. You can then add additional filters on a per-version basis (See Filter by API Version below).

In the metadata.xml file, include each filter you would like to apply 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:

• First, filters that apply to all documents
• Next, API Version filters

The example below shows a simple metadata.xml file with one API version, apiversion12345.acmecorp; 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, make sure you represent the names of referenced objects, such as license, scope, or file names, exactly. 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">apiversion12345.acmecorp</APIVersionID>
    <target>documents/index.htm</target>
    <roles>
      <role name="InvitedUser"/>
    </roles>
  </metadata>
  <metadata>
    <target>documents/addPayment.htm</target>
    <operations>
      <operation name="addPayment"/>
    </operations>
  </metadata>
  <metadata>
    <target>documents/fullscope-public.htm</target>
    <scopes>
      <scope name="fullscope-public"/>
    </scopes>
  </metadata>
  <metadata>
    <target>documents/license_public_gold.htm</target>
    <licenses>
      <license name="Gold"/>
    </licenses>
  </metadata>
</metadataconfig>

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.

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

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. Scopes are mapped to API operations using the Scope Mapping function on the API > Details page.

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

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 documents. Scopes are mapped to API operations using the Scope Mapping function on the API > Details page.

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

Specifying target files: filter by file

You can filter documents based on a specific file by specifying a regular expression, as shown in the examples above.

For example, you might want to define a filtering rule that applies to a specific PDF file, sample.pdf. Using this example you would specify the following in the <target> node:

<target>apis/sample.pdf</target>

Specifying target files: filter by document type (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 .htm files in the /Documents folder you could define the <target> node as follows:

<target>.*\.htm</target>

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

<metadata>
  <APIVersionID xmlns="http://soa.com/xsd/api/1.0">apiversion12345.acmecorp</APIVersionID>
  <target>documents/*\.htm</target>
  <roles>
    <role name="InvitedUser"/>
  </roles>
</metadata>

Or, you might want to filter so that a rule applies to all Microsoft Word .docx files in the /documents folder:

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

You can also specify multiple <target> filters. If you want to specify a rule that applies to all .htm and .jpg files in the /Documents folder you could include two <target> nodes:

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

This expression should be placed after the <metadata> tag if your XML file does not include an API Version filter. If it does include an API Version filter, the expression should be placed before the filter. Refer to the sample metadata.xml file above.

Specifying target files: filter by API version

In addition to applying filters to all API documentation, you can further filter an API version using the <api:APIVersionID> filter. You configure this filter by extracting the API Version ID plus tenant name (for example, apiversion400.acmecorp) from the API > Documents URL of your platform.

Example URL:

/api100.acmecorp/versions/apiversion400.acmecorp/documents

In your metadata.xml file the resulting entry might look similar to the following, which limits access to all .htm files for the specified version so that it is only visible to users with visibility of the Gold license:

<metadata>
  <api:APIVersionID>apiversion400.acmecorp</api:APIVersionID>
  <target>.*\.htm</target>
  <licenses>
    <license name="Gold"/>
  </licenses>
</metadata>

This example illustrates filtering by API Version plus a specific document:

<metadata>
  <api:APIVersionID>apiversion400.acmecorp</api:APIVersionID>
    <target>apis/sample.htm</target>
      [API documentation filter goes here]
</metadata>

This example illustrates filtering by API Version plus a specific document type:

<metadata>
  <api:APIVersionID>apiversion400.acmecorp</api:APIVersionID>
    <target>apis/*\.html</target>
      [API documentation filter goes here]
</metadata>

Table of Contents

If you have selected a set of files to display in the Table of Contents that displays in the left navigation in the API > Documents section of the platform, the content dynamically displays based on the filters specified for all API documentation or for a specified API version.

Content-based tagging: using documentation tags

It's best to organize your content so that entire files are viewed or hidden based on a user's visibility settings. However, in some cases you'll also need to show or hide different sections of content within one file. At minimum, you'll probably want to organize your documentation index page to include links to the different files that are tagged in the metadata.xml file and make the links visible only to users with access to the applicable licenses, scopes, or operations.

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 two things:

• Add some lines of code at the top of the HTML file. See Content-based tagging: Setting up the file.
• Tag the applicable content within the file. The following tags are supported:
  • showforlicense
  • showforscope
  • showforoperation
  • showforanonymoususer
  • showforloggedinuser

Note: Tags are mutually exclusive and cannot be nested.

Content-based tagging: Setting up the file

If you want to use the content-based documentation tagging feature to control the visibility of specific pieces of content within a file so that they are displayed to the viewing user based on the user's visibility access rights, you'll need to set up some lines of code in the <head> tag of the HTML file, as shown below.

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

2. Within the <head> tag, after the <title> tag, add the following lines:

   <link rel="stylesheet" type="text/css" href="/resources/style/base.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/{Version}/resources/javascript/dynamic_docs.js"
     type="text/javascript"></script>

   Note: See important note below with regard to the {Version} variable in the last line above.

3. Repeat for each file that will have content-based tagging.

Important: if you want to use dynamic content in your files you must reference the above two JavaScript files. In the second link above, you can use whatever value you want to use in the /{Version}/ part of the path. For example, you could use your API version, API doc version, or the platform 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, you'll want your users to have 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 {Version} variable in the file path. Changing the value ensures that when a user accesses your documentation, their browser will reference the latest version of the file.

showforlicense

To restrict documentation visibility by license, specify the license names in the showforlicense tag, adding one or more license names separated by commas. 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 API documentation.

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

showforscope

To restrict documentation visibility by scope, select the API-wide Mapping option or Operation-specific Mapping option in API Details > Scope Mapping >Edit Scope Details. In the API documentation HTML file, configure the tags as follows, adding one or more operation names separated by commas.

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

showforoperation

To restrict documentation visibility by operation, select the Operation-specific Mapping option in API Details > Scope Mapping > Edit Scope Details. In the API documentation HTML file, configure the tags as follows, adding one or more operation names separated by commas.

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

showforanonymoususer

If there is some content in your documentation that you want to share broadly to all viewers, whether logged in or not, you can apply the showforanonymoususer tag, as shown below.

<soa:showforanonymoususer>
  <div class="soa-ui-cm-dynamic-docs">
    <div class="get-started">
      <p><a class="button soa-ui-cm-button" href="#/home/signup">Sign Up</a></p>
    </div>
  </div>
</soa:showforanonymoususer>

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">
    <div class="get-started">
      <p><a class="button soa-ui-cm-button" href="#/home/signup">Sign Up</a></p>
    </div>
  </div>
</soa:showforloggedinuser>

Using Multiple Tags

You can specify multiple entries of the same type (licenses, scopes, or operations) and separate them with a comma. An example for scopes is shown below.

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

Test

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

• Verify that the <html> tag, <head> tag, <div> tags, and visibility tags are properly configured in any applicable HTML files.
• 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. It is in the format apiversion{nnnnn}.{tenant}. For example, apiversion10368.acmecorp.
• Verify that links to tagged sections are also tagged.
• Verify that the scope and operation names you specified in the visibility tags are valid. Scopes are mapped to operations on the Scope Mapping > Edit API Scope page. If scope names are missing or incorrect, consult with your Business Administrator.
• 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 > Details page.
• Upload your files. See How do I upload my documentation files?
• 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 > Documents section.
• If you make changes to licenses, scopes, or operations, update the API documentation HTML files accordingly.

Back to top

How do I upload my documentation files?

You can upload HTML files and associated images, PDF files, or other content to the API > Documents section of the platform using the File Manager.

There are two upload options:

• Upload files individually.
• Upload multiple files at once using a ZIP archive file.

  If you use a ZIP file, make sure the files within the ZIP don't include extra folders that you don't want in the path. When you upload, the file is unzipped automatically using the paths, if any, specified within the ZIP file. At minimum, the file that is the entry point to your documentation should be in the /documents folder.

To upload your files via the File Explorer:

1. Navigate to API > API Name > Documents.
2. Click the File Explorer icon in the upper-left corner of the documentation panel. The File Explorer appears.

   

3. Click Upload a File or Upload a Zip Archive.
4. In the File Upload box, navigate to the location of the individual file or ZIP file you want to upload. Choose the file, and then click Open.
5. Click Upload.

Back to top