Using API Agent

Edit online

You can use API Agent for end-to-end API publishing and testing. What follows here are sections with details about what to expect when using the API Agent plug-in and a sample end to end flow scenario which you can walk through to get an understanding of how the agent works and the capabilities available in the agent.

Administrators can assign appropriate roles to enable API Agent for specific developers within their organization. This selective enablement ensures that the tool is used effectively within the right context. After the admin configures the sources, developers can install the Visual Studio Code plug-in and start integrating it into their workspace. For more information, see the API Agent user roles section.

Best practices

The API Agent extension is a tool used in Visual Studio Code to assist with API management. To ensure proper functions, it is essential to have the extension window at full height and at least 1/3 width of the window.

Understanding prompts in the documentation
When you see a command in documentation, it's essential to understand how to use it correctly.

  1. If a command contains a placeholder, such as [apiName], you need to replace it with your own text. For example,

    • Command: Run test cases for [apiName]:[version]
    • Replacement: Run test cases for ( bookshop-api-3:1.0)
    Note: Ensure that you replace [apiName] with the actual name of your API to run the command accordingly.

  2. To populate the placeholder, such as [@file]:

    • The document might have the following prompt: remediate api [@file] using spectral-owasp ruleset. Replace it with remediate api @bookstore.yaml using spectral-owasp ruleset.

    To replace [@file], you need to trigger the @ symbol to access the files in your Visual Studio Code workspace. Then, select the wanted file to upload to the agent.

Keeping the session active
To keep the session active, you need to clear out any temporary or residual data that might be causing problems, and then refresh the system to ensure that it is in an updated state.
To keep the session active and refresh, complete the following steps:
  1. Enter CMD + SHIFT + P to open the Visual Studio Code command palette.
  2. In the command line, enter Developer: Reload window.
  3. In the command line, enter API Agent: Logout.
    Note: This command removes your login session but you need to do the authentication process again. However, the login information (pOrg, login URL, and more) is still cached
  4. To remove all cached login information after logout, in the command line, enter API Agent: Clear session from workspace state and reload.
    Note: When a plug-in is deleted or deactivated in Visual Studio Code, the cached login information persists. This means that when you again download the plug-in, the URL field is populated with your last used URL.
Debugging process
For debugging purposes, there are two areas to explore in the Visual Studio Code command palette.
To view the Visual Studio Code side of the extension, complete the following steps:
  1. Enter CMD + SHIFT + P to open the Visual Studio Code command palette.
  2. In the command line, enter Show Output Channels, and select the command from the list.
  3. In the output channels list, select API Agent Debug Logs.
  4. Visual Studio Code extension displays the following information:
    • Login and session data
    • Reinitialization of the extension after changing tabs
To view the chat webview side, complete the following steps:
  1. Enter CMD + SHIFT + P to open the Visual Studio Code command palette.
  2. In the command line, enter Developer: Open Webview Developer Tools, and select the command from the list.
  3. You can view the webview developer tools, where you can access the following information:
    • Console tab: view logs and console output
    • Network tab: inspect REST calls being made
Attaching and downloading Files
To attach and download a file, complete the following steps:
  1. To attach a file, you must trigger the file menu by typing @ and then selecting the file.
    Note: The maximum file size is 1MB, and the filename must not contain any spaces or special characters.
  2. If you have copied and pasted a command like validate api @testapi.yaml, delete back to the base command validate api and retype the @ to trigger the file menu.
  3. Select a file from the file menu that appears after typing @.
  4. When a next action button includes a reference to a file, for example, remediate api [@file] using spectral-owasp ruleset, you must replace [@file] with a newly attached file by triggering the file menu with the @ symbol.
  5. To delete the file name in the command line, delete the command and reenter validate api.
API Agent reload and logout issues
  • If you have not been using your chat for a while, the token used with API Connect expires during this time and if you continue to have a conversation, it displays an Error: Unauthorized and autolog you out. You need to do the login process again.
  • To properly clear out resources, you must use the logout option within the plug-in rather than the Visual Studio Code managed sign-out option.
Important:
  • Plug-in rename: The API Agent plug-in has been renamed from API Assistant. If you have the old version, delete it before downloading the new one.