APIs | Content Development Guidelines

Content Development Guidelines

This section provides guidelines that API providers can use to manage API content such as API documentation and legal agreements.

Publishing:

What API documentation publishing options does the platform provide?

After adding an API, you can add documentation for your API in the API > Documents section using one or more of the following methods:

HTML—You can upload HTML documentation and associated support files (e.g., graphics) using the File Explorer.
Methods—You can add documentation for RESTful services using the Swagger UI add-on that is integrated into the API > Documents section. When you add a RESTful service using the Add a New API Wizard, the system adds the methods/operations defined in the API to a pre-defined system template composed of Swagger HTML, JavaScript, and css assets. You can then add your documentation content and configure what aspects of the API documentation you would like to show or hide based on the state of your current API.
Reference—If you already have API documentation developed and published to a website, you can create and upload a custom topic that links to the reference documentation.

Does the platform require that HTML files be saved in a specific code format?

Yes, all HTML files must be saved in UNIX code format. This requirement is to ensure optimum compatibility across operating systems.

One method you can use to verify if your files have the correct format is to select View > Document Properties in TextPad. If the "Code set" is UTF-8, and "File type" is UNIX, then the code format your file is saved as is correct.

Note that you must also add the following meta data tag in your <head> tag to indicate that the file code set is UTF-8:

<meta http-equiv="Content-Type" content="text/html; charset=utf-8">

What is File Explorer and what functionality does it offer?

File Explorer is a simple file management tool that allows you to upload documentation source files to various parts of the platform UI:

In the API > Documents section you load File Explorer by clicking the icon in the upper left-hand corner of the screen.
In the Legal section, you load File Explorer by clicking Manage Files.

File Explorer includes the following functionality:

File Manager Features	Description
Go up a Directory	Allows you to navigate the \documents default directory.
New File	Allows you to create a new HTML file and add it to the current directory.
Upload a File	Allows you to upload a single HTML, .swg, and associated documentation support files (e.g., graphics).
Upload a Zip Archive	Allows you to upload a zip archive into the \Documents folder.
Show in TOC	A checkbox that allows you to display a file in the left-hand navigation underneath the Documents menu.
Default	A radio button that allows you to identify the default file that will load when Documents menu is selected.
Rename	Allows you to rename a file. When selected a File Name popup displays where you enter the file to be renamed.
View Direct	Allows you to view the current file via a URL address.
Set Display Name	Allows you to configure the name that will display in the Documents section if the Show in Toc option is selected. When selected, a File Name popup displays where you enter the file to be renamed.
Delete	Allows you to delete a file by clicking "x."

What is Swagger and how does it work?

Swagger by Wordnic (http://swagger.wordnik.com/) is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. It produces dynamically generated documentation that includes methods, parameters and models. The platform includes an implementation of Swagger that works in conjunction with the Add a New API Wizard.

When you define an API, the structure is dynamically generated and added to a predefined Swagger template. The documentation-ready structure is available in the API > Documents section where you add a title, description, implementation notes, and parameter information.

The documentation content is stored in a resources.swg file. Using the File Explorer you can add this file to your table of contents make it the default display document when you click the API > Documents menu. You can also add the Swagger document URL to your HTML documentation.

Editing:

Who can edit API and Legal Agreement content?

API documentation and legal content in the platform can be uploaded and managed by Site Administrators, API Providers, and designated Administrators of an API.

What document management tasks can I perform in the platform?

Within the platform, editing of API and Legal Agreement content is limited to:

Uploading API and legal agreement documents via the File Explorer.
Defining name and description of legal agreements.
Activating / deactivating visibility of legal agreements in API wizards.
Downloading legal agreement usage reports.

Development of document content must be performed outside of the platform, with the exception of Swagger API documentation which is entered directly into the templates in the API > Documents section.

How do I edit HTML page content?

The platform supports content pages written in HTML. You must create your API and legal documents in an external HTML authoring tool and upload the documentation using File Explorer.

What are the Swagger controls and how do I edit page content?

The Swagger documentation includes a series of page controls for displaying and navigating through the method documentation as follows:

Swagger Controls:

Show / Hide—A toggle that expands or collapses the API methods.
List Operations—Displays the API operations.
Expand Operations—Displays the Implementation Notes and Parameter section of the operations.
Raw—Displays the JSON code that comprises the resources.swg file.

Editing Options:

You can add / edit the following areas in Swagger documentation. First navigate to API > Documents page that includes the Swagger and perform the desired step.

To add a page title:

Click into the "Click here to add a title" text box and specify your documentation title.
To save the title, click outside of the text box.

To add a description:

Click into the "Click here to add a title" text box and specify your documentation title.
To save the title, click outside of the text box.

To add implementation notes to an API operation:

Go to a method and select List Operations.
Select the operation you would like to add implementation notes to and click Expand Operations.
Double click under the "Implementation Notes" label, select "Double-click to add Notes." A text box displays.
Enter your data and click outside the text box to save.

To add a parameter description to an API operation:

Go to a method and select List Operations.
Select the operation you would like to add implementation notes to and click Expand Operations.
In the Parameters section, select "Double-click to parameter description." A text box displays.
Enter your data and click outside the text box to save.

How do I set the default documentation page using File Manager?

To set the default document page that will load when you click API > Documents:

Navigate to API > API Name > Documents.
Click the File Explorer icon (in upper-left corner of the pages)
In File Explorer, click the Default radio button. The selected document will automatically display first when you select the API > Documents menu.

How do I set the default documentation page using a parameter file?

When you upload a document or artifact to the API > Documents section using the File Manager, a toc.apiversion file is created (format: toc.apiversionXXXXX.<productname>.json). Information about your document upload, toc display name, and default toc file are stored in this file.

Using a file editor, you can manually update the "defaultFile":"<filename>.html" parameter of the file to set your default HTML document.

If you currently have a HTML document loaded and would like to switch back to the Swagger UI, you can delete this parameter and reset the default document back to Swagger.

To set the default documentation page in a toc.apiversion file

In the file system, navigate to the Documents folder of your API.
If you previously uploaded an HTML file using File Manager, open a file editor, locate the toc.apiversionXXXXX.<productname>.json file and drag the file into the editor.
Update the HTML file in the "defaultFile":"<filename>.html" parameter to the new default.
If you would like to switch back to the Swagger UI, remove the "defaultFile":"<filename>.html" parameter.
Save the file.
Return to the platform UI and clear the cache. The selected default document will display on the API > Documents page.

How do I add a file to the documentation table of contents?

To add a file to the documentation table of contents:

Navigate to API > API Name > Documents.
Click the File Explorer icon (in upper-left corner of the pages)
In File Explorer, click the Show in Toc icon. The filename displays in the Documents table of contents. If you would like to change the display name of the file, see How do I set the file display name in the table of contents?

How do I set the file display name in the table of contents?

To set the display name of a file in the table of contents:

Navigate to API > API Name > Documents.
Click the File Explorer icon (in upper-left corner of the pages)
In File Explorer, click the Set Display Name icon.
The Display Name dialog box displays. Enter the name you would like to display in the table of contents for this file and click OK. The name of the file changes in the table of contents.

How do I rename a file in File Explorer?

To rename a documentation source file:

Navigate to API > API Name > Documents.
Click the File Explorer icon (in upper-left corner of the pages)
In File Explorer, click the Rename icon.
The File Name dialog box displays. Enter the new filename and click OK. The filename changes in the File Explorer display.

How do I view a file in File Explorer?

To view a documentation source file:

Navigate to API > API Name > Documents.
Click the File Explorer icon (in upper-left corner of the pages)
In File Explorer, click the View Direct icon. The selected document views in the browser.

How do I delete a file using File Explorer?

To delete a document source file:

Navigate to API > API Name > Documents.
Click the File Explorer icon (in upper-left corner of the pages)
In File Explorer, click the Delete icon.
At the confirmation prompt, click OK.

Styles:

What are the general HTML coding guidelines?

Following the guidelines below will help ensure your fileset is consistent in structure, with clean, well-formed HTML that will look correct when viewed under varying circumstances such as in different browsers and in search results.

Bear in mind these points:

Use an HTML editor that doesn’t add extra tags into your code. Working with HTML in a word processing program, for example, can result in complex HTML with many extra tags. This can be difficult to work with and to debug when needed. There are free HTML editors available for download, and there are more sophisticated tools available for purchase that provide a user interface and a WYSIWYG display without adding complexity to the HTML. Invest in a tool that delivers clean HTML.

Include the <head> tag with links to your style sheets. For example, the default Community Manager Help uses the default site style sheet (base.css) and document.css style sheet. Document.css includes all the custom styles for the documentation and takes certain elements (e.g., spacing) from the base.css. Using these style sheet examples, your <head> tags would look something like the following:

<html>
<head>
<title>Document Title</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="../../../../resources/style/reset.css" rel="stylesheet" type="text/css" />
<link href="../../../../resources/style/base.css" rel="stylesheet" type="text/css" />
<link href="../../style/document.css" rel="stylesheet" type="text/css" />
</head>

<body>
HTML Content
</body>

</html>

Include an appropriate page title tag (<title>) within the <head> tag in each file. Although the page title doesn’t show up when the page is viewed in the platform, it’s picked up by the Search feature and displayed with the search results. For example:
<title>XXX API | Page Title</title>
The main heading for any documentation page is <h2>. Use of <h1> is reserved by the platform; <h2> is the top heading level for API docs.

What style sheets do I use for my HTML API documentation?

You might find that the default styles in the platform work fine for you and are all you need. If need custom styles, you can create or upload a CSS file. You can add or edit a CSS file in the same way as you do an HTML file.

Note: If you have a custom CSS file for your documentation, make sure it’s stored in the \userdocs\style subdirectory. You can create this directory via the File Explorer if it doesn’t already exist. Your CSS filename must not include illegal characters, but it must have the extension .CSS and be stored in the /css subfolder.

Click here to download a sample API documentation style sheet. These styles are part of the document.css style sheet located userdocs\style directory. If you would like to develop your API documentation using these styles, or choose to update these styles, make sure you update the document.css file before uploading your documentation to the site.

The following paths illustrate the location of the \style directory relative to the \learnmore directory. This is where the current document.css file is stored. Based on your requirements you can choose to store your \css in a different location (e.g., in the same directory as your files or in a \css folder in your \Documents directory).

\userdocs\home\learnmore
\userdocs\style

What style sheets do I use for my Swagger documentation?

SOA Software provides a pre-defined Swagger style sheet that is internal to the product and is applied to all dynamically generated Swagger documentation structures.

What style sheets do I use for my legal agreements?

Legal agreements use the platform default style sheets. Active legal agreements display in the API Access Wizard when a user requests access to your API. To ensure that your legal agreement displays properly in this wizard, download the legal agreement sample file and use it as a template to structure your legal agreement HTML.

Click here to download a sample legal agreement file.

What document styles can I use?

API documentation content should be defined using standard HTML and CSS files. In choosing styles, make sure you’re aware of any corporate or team guidelines, and be consistent across your file set so that users see the same styles and typographical conventions as they read your content.

Can I add other types of content?

As well as formatted HTML for your content, and CSS files to control the visual display, you can upload some other types of content and link to them from your HTML files. For example, you can use the following:

Images: Upload any image files supported by browsers, such as JPG and PNG, and put them in the same folder as your HTML files, or in a subfolder.
Flash objects: Upload SWF files and place them in your HTML files or set them up as external links to be viewed in a separate browser window. For example, here’s a code sample that illustrates how to link a training video done in Flash:
```
<a href="filename.swf"  target="_blank">Training video</a>
  
```
The extra property after the filename, target="_blank", tells the browser to open the file in a new window instead of displaying the content in the current window (the platform UI).
ZIP files: These are particularly useful if you’re offering an SDK, or if you want to offer your API documentation as a download as well as making it available in the platform. You can upload a ZIP file via the File Explorer and then link to it from an HTML page.
PDF files: Upload PDF files and link to them from your HTML files. Note: When you link to a PDF file, be sure to specify a target window of “new window.”

Content Organization:

How do I organize my API and legal agreement documentation files?

To organize your API and legal documentation files:

In the installation directory of the platform tenant, a /documents and /legal directory are automatically created as part of the adding the API using the Add a New API Wizard. These directories can be viewed when you launch File Explorer in the API > Documents or API > Legal sections of the platform.
The path of the /documents and /legal folder displayed in the File Explorer includes an API ID (apixxxxx where "xxxxx" represents a number) that is assigned when the API is added to the platform. The /documents path is /content/api/apixxxxx.open/documents. The /legal path is /content/api/apixxxxx.open/legal.
Inside the /documents directory create a style sheet directory (/css) to store any custom API documentation style sheets. This style sheet must work in conjunction with the document.css style sheet (located at http://<tenanthost>:<port>/style>/document.css).
You can also create an assets directory (/assets) in the /documents directory to store image files that might be included in your documentation.
Download the platform style sheet, document.css, from the http://<tenanthost>:<portstyle>/document.css directory. A sample API documentation style sheet can also be found here. This style sheet can be used on your local machine to develop your documentation. Click here for a doc sample that illustrates use of the document.css style sheet.
Copy any custom style sheets to the /documents/css directory where you will be storing your API documentation.
If you would like to upload single documentation files using File Explorer, see How do I upload my API documentation?
If you would like to upload your documentation using a zip file, see How do I zip my documentation files?
Here is an example of what the /documents directory looks when you load File Explorer for the first time after creating an API:
Here is an example of what the /legal directory looks when you load File Explorer for the first time after creating an API:
If you would like to upload your documentation using a zip file, see How do I upload my legal agreements?

How do I zip my documentation files?

You can upload a zip file that containers your documentation using File Explorer.

To upload a zip file using File Explorer:

Navigate to API > API Name > Documents.
Click the File Explorer icon (in upper-left corner of the pages)
In File Explorer, click Upload a Zip Archive.
In the File Upload box, navigate to the location of the zip archive file you want to upload. Choose the file, and then click Open. The zip file loads and expands into the /documents folder.

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 that includes introductory text and includes a link to your website. For example:

Example HTML:

<title>My API</title>
<p>Please go <a href="http://myapi.com/docs/reference/api/" target=”_blank”>here</a> to see the details of this API.</p>

Note: If you are linking to an external site, include target=”_blank” in the HTML file to open the external site in a new window.

To upload your reference file see: How do I upload my API documentation?

File Upload:

How do I upload API documentation?

The API > Documents section includes an interface that allows you to add and maintain your API documentation.

Documentation must be in HTML format.
It should follow the style conventions defined in the platform default style sheet (document.css) located in the apidocs\styles\ folder, and your custom API style sheet (if used) located in your <apiname>\documents\css directory.
You can configure any document to be the top-level/intro page that displays when you click API > Documents. See How do I set the default documentation page using File Manager? or How do I set the default documentation page using a parameter file?.
All documentation files must be uploaded to the \documents folder that is auto-generated when an API is created using the Add a New API Wizard.
If you would like specific files to display in the Documents left navigation, you can click the Show in TOC checkbox in the File Explorer. See How do I set the file display name in the table of contents?

You can upload documentation using File Explorer. You can upload documentation on a file by file basis, or you can upload a zip file.

To upload API content via the File Explorer:

Navigate to API > API Name > Documents.
Click the File Explorer icon (in upper-left corner of the pages)
In File Explorer, click Upload a File.
In the File Upload box, navigate to the location of the file you want to upload. Choose the file, and then click Open. After uploading your files, set the default page. See How do I set the default documentation page using File Manager? or How do I set the default documentation page using a parameter file?

Can I upload existing API documentation and use it in the platform?

Yes, you can upload your existing file set into the platform via File Explorer. Make sure that relative file locations in the platform are the same as in your source files so that you don’t break any links between files (if any exist). The content also needs to be organized in the required document structure. See How do I organize my API and legal agreement documentation files?

Note: You must include head and body tags that reference all the css style sheets used in your API documentation.

How do I configure my API documentation so it's searchable in the platform?

If you would like your documentation to be searchable in the platform, include the <title> tag (for example, <title>Doc Name</title>) at the top of your HTML file, within the <head> tag.

The example below shows the structure and sequence.

<html>

<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

  <title>Searchable Text</title>

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

<body>

<p>Document Content</p>

</body>

</html>

How do I upload my legal agreements?

The APIs > Legal section provides functionality that allows you to upload and manage legal agreements that pertain to each API. An API may require one or more legal agreements. Legal agreements with an approved status display in the API Access function. A user must accept the terms of the legal agreements to gain access to API functionality.

Legal agreements must be in HTML format.
A legal agreement should follow the style conventions defined in the platform default style sheet (document.css) located at http://tenanthost:port/content/style/document.css.
Legal agreements can be any unique filename.
All legal agreement files must be uploaded to the \legal folder.

To upload the legal agreement file via the File Explorer:

Navigate to API > API Name > Legal.
Click Manage Files.
In File Explorer, click Upload a File.
In the File to Upload dialog box, click Browse to navigate to the location of the file you want to upload. Choose the file, and then click Open.
Click the Publish checkbox to add the document name to the Agreements list accessible via Manage Agreements.
Click outside of the File Explorer to exit.

Testing

How do I test updated content?

When you add or change content, it’s a good idea to preview it in the browser to make sure it looks correct and no symbol characters are displaying. For example, if you have more than one space separating a word, the additional space may be displayed as a symbol character in some browsers.

When you save the content, it’s displayed for you in your own browser window. However, another user reading API documentation might use a different browser. Since there are differences between browser defaults that might affect the visual display, it’s a good idea to check how your content looks in the most popular browsers.

Simply copy and paste the URL. Although you need to be signed in to edit the content, no login is required for viewing most content pages.

It’s a good idea to make sure your content changes look OK in Internet Explorer, Firefox, and Google Chrome.

Updating

How do I update API and legal agreement documentation I've added to the platform?

To update API and legal agreement documentation that you've added to the platform you must upload a new file using File Explorer. See How do I upload my API documentation? or How do I upload my legal agreements? for details.

Content Development Guidelines

Table of Contents

Publishing:

Editing:

Styles:

Content Organization:

File Upload:

Testing:

Updating:

Publishing:

What API documentation publishing options does the platform provide?

Does the platform require that HTML files be saved in a specific code format?

What is File Explorer and what functionality does it offer?

What is Swagger and how does it work?

Editing:

Who can edit API and Legal Agreement content?

What document management tasks can I perform in the platform?

How do I edit HTML page content?

What are the Swagger controls and how do I edit page content?

To add a page title:

To add a description:

To add implementation notes to an API operation:

To add a parameter description to an API operation:

How do I set the default documentation page using File Manager?

To set the default document page that will load when you click API > Documents:

How do I set the default documentation page using a parameter file?

To set the default documentation page in a toc.apiversion file

How do I add a file to the documentation table of contents?

To add a file to the documentation table of contents:

How do I set the file display name in the table of contents?

To set the display name of a file in the table of contents:

How do I rename a file in File Explorer?

To rename a documentation source file:

How do I view a file in File Explorer?

To view a documentation source file:

How do I delete a file using File Explorer?

To delete a document source file:

Styles:

What are the general HTML coding guidelines?

What style sheets do I use for my HTML API documentation?

What style sheets do I use for my Swagger documentation?

What style sheets do I use for my legal agreements?

What document styles can I use?

Can I add other types of content?

Content Organization:

How do I organize my API and legal agreement documentation files?

How do I zip my documentation files?

Can I link to API documentation on a different site?

File Upload:

How do I upload API documentation?

Can I upload existing API documentation and use it in the platform?

How do I configure my API documentation so it's searchable in the platform?

How do I upload my legal agreements?

Testing

How do I test updated content?

Updating

How do I update API and legal agreement documentation I've added to the platform?