Learning

API Documentation Maintenance

Add and maintain API documentation.

Note: For information about tagging API documentation for visibility by different audiences, see API Documentation Tagging.

Table of Contents

  1. What is the API documentation maintenance process?
  2. Who can upload API documentation content?
  3. How do I add API documentation?
  4. How do I manage documentation for more than one API version?
  5. Can I link to API documentation on a different site?
  6. What are the content development guidelines for API documentation?
  7. How do I upload my API documentation files?
  8. How do I download my API documentation files?
  9. I'm not using doc tagging; why do I still need a metadata.xml file?
  10. How do I link to the API-specific Test Client for my API, so developers can click through from my API documentation in Simple Dev theme?

What is the API documentation maintenance process?

You'll need to develop your API documentation outside the platform in your own HTML editor. Once your content is ready you can upload it to the site.

Back to top

Who can upload API documentation content?

You can upload documentation for a specific API if you are logged in and have one of the following roles:

  • 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. See Using File Manager.
  • By using the Swagger documentation tool that is integrated with the platform. See Using Swagger.

Back to top

How do I manage documentation for more than one API version?

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:

  • Differentiate file names by version. For example, if you have two versions, with some files shared between versions and some files different for each version, you could name the 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.

Back to top

Can I link to API documentation on a different site?

You can link to any external site from your API documentation. For example, if you already have a website established for your API and/or your documentation, you could upload a file with some introductory text and a link to direct users to your website for the information about your API.

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 examples, see Can I link to an external site?

Back to top

What are the content development 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

How do I upload my API 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 that you are in the right folder when you upload it, and that it doesn't include extra folders that you don't want. When you upload, the file is unzipped as part of the upload process, 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 API documentation 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

How do I download my API documentation files?

You can download a ZIP file of the documents directory for your API, including all files in the directory and all subfolders and their contents. You can download a ZIP of any content you are authorized to view and edit. Follow the instructions below.

To download your API documentation 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 Download Directory.
  4. Choose to open or save the file.

Back to top

I'm not using doc tagging; why do I still need a metadata.xml file?

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.

Back to top

How do I link to the API-specific Test Client for my API, so developers can click through from my API documentation in Simple Dev theme?

Platform app developers have access to the Test Client tool, which allows them to test out different APIs. Test Client includes a drop-down list, where app developers can choose from a list of available APIs that the current app has a contract with.

In Simple Developer theme, an API-specific version of the new Test Client testing tool is available, to facilitate testing of an individual API from the API page of the Developer Portal. The API Admin can also use this to include an API-specific link to Test Client within the API documentation. When using Test Client in the context of a specific API, developers can invoke APIs that support anonymous access, use the credentials for one of their apps, or use a custom app identity.

The API-specific version of Test Client is not part of the standard user interface, but you can construct the URL and include it in your API documentation. App developers reading your API documentation can click through and test out your API. This API-specific version of Test Client does not give access to all the app developer's APIs, just the one that's in the URL.

The URL is:

{protocol}//{hostname}/#!apis/{APIID}/versions/{APIVersionID}/testclient

For example:

http://acmepaymentscorp.com/acmepay/#!apis/12770263-e036-4222-b8eb-87d33676d3ad.acmepay/
versions/9e3846ee-bbbf-4982-82ca-5a2411ec619b.acmepay/testclient

To construct the URL for your specific API, follow the instructions below. You can then link to this page from your platform API documentation. For information on including links in platform API documentation, see How do I code links in Simple Dev?

To construct the URL for an API-specific version of Test Client:
  1. Go to the URL for your implementation of Simple Developer theme and log in.
  2. At the Welcome page, copy the URL up to #!, omitting the welcome from the end of the URL. It will look something like the below:
    http://acmepaymentscorp.com/acmepay/
  3. Get the APIID and APIVersionID for your API. For example, you could:
    • Go to the URL for your implementation of Default Theme and log in.
    • Go to the API Details page for your API and copy the URL. It will look something like the below:
      http://acmepaymentscorp.com/#/api/21bfe816-5260-4444-ae77-bd2c047174f8.acmepay/versions/
      7ba40d5f-3c22-4b8f-ac9d-317cbee4b83f.acmepay/details
    • In the above, the first ID, after /api/, is the APIID, then /details/, and then the APIVersionID. Copy that whole portion of the URL, beginning with the APIID and ending with the APIVersionID, to use in constructing the URL for your API-specific Test Client.
  4. Join together the part of the URL from Step 2, and the part from Step 3, and add /testclient at the end.
  5. Test the URL to make sure you have it right.
To reference the URL for an API-specific version of Test Client in your API documentation:

Once you have the URL, you can reference it with a direct inline link from your API documentation. To have the Test Client display in a separate browser tab, use the Target attribute _blank, as shown below.

<p>To test your app with our API, try out the 
<a href="{protocol}//{hostname}/{Tenantname}/#!apis/{APIID}/versions/{APIVersionID}/testclient" target="_blank">
Test Client testing tool</a>.</p>

To upload your file to the API documentation folder in Simple Dev theme, see Where do I upload API documentation for Simple Dev?

Back to top