Attaching documents to an API

Edit online

You can associate an input document that includes the RAML, Swagger, or WSDL specification. Also you can associate other documents such as programming guides, sample code, script files, and project plan with an API. For example, SOAP APIs can contain external documents such as functional requirements, error messages, and release notes.

Before you begin

You must have the Manage APIs functional privilege to perform this task.

About this task

When you attach a document to an API, keep the following points in mind

  • You cannot attach or modify a document to the API if it is in an active state. Deactivate the API before you attach or modify a document.
  • webMethods API Gateway relies on file extensions to determine a file's type. When you upload a file from your local machine to the API, be sure that the name of the file on your local machine includes a file extension. The file extension helps webMethods API Gateway to determine the file's type and attach it correctly to the API.
  • You cannot upload types of files that are restricted for attaching as the input document to the API.

    webMethods API Gateway helps restrict certain kinds of files from being uploaded to the API, based on the file extension. The list of restricted files might vary depending on the file extensions That are configured. You can configure the file extensions in the apiDocumentsRestrictedExtension property under Administration > Extended settings section.

    When you try to upload a file type that is restricted, webMethods API Gateway prompts you with an error message.

  • By default, several standard file extensions are blocked in webMethods API Gateway, including any file extensions that are treated as executable files by Windows Explorer. The file extensions that are blocked by default are, .bat, .bin, .dll, and .exe.
  • You cannot upload files that exceed the maximum allowed size for the API.

    webMethods API Gateway helps you apply a limit on the maximum file upload size to the API. The maximum file upload size is configured in the apiDocumentsUploadSizeLimitInMB property under Administration > Extended settings section.

    When you try to upload a file that exceeds the maximum file upload size, webMethods API Gateway prompts you with an error message.

  • You can rename an uploaded document. When you rename a document, only the display name of the document might be modified, not the document itself. If you want to modify the document as well, you must delete the file attachment, and attach the latest file.

Procedure

  1. Open the menu options and select APIs.
    A list of all registered APIs appears.
  2. Select the required API.
    The API details page appears.
  3. Click Edit.
  4. Click Documentation.
  5. Click Browse to select a file and upload it.
  6. Rename the document in the Display Name field.
    This name is the display name of the document in the API details page.
  7. Click Add. The attached document is listed in a table.
  8. Repeat steps 5 to 7 for each document that you want to attach to the API.
  9. Click Save.