[Technology Preview] Using API Assistant for error remediation

You can use the API Assistant to analyze your OpenAPI 3.0 specification validation errors, generate potential AI fixes, and apply them to your APIs. Speeding up the delivery of your APIs, and reducing validation errors.

The API Assistant uses the IBM watsonx Granite LLM models to help you improve the quality of your APIs, and bring them to your consumers faster. Take advantage of the API Assistant to quickly generate AI fixes for your API definitions.

Technology Preview

This feature is provided as a technology preview. As such, the feature might not be fully functional in your environment and support is limited. In addition, the feature’s appearance, functionality, and name are subject to change both in this release and in later releases of API Connect.

Limitations

The API Assistant error remediation feature is subject to a rate limit on calls to the AI generator. For best performance, use API Assistant on moderately sized APIs.

In addition:
  • You must use a Basic or Advanced subscription (Trial subscriptions do not have access).
  • You must work online in API Manager (working locally in API Designer is not supported).
  • Your API definition must conform to the OpenAPI 3.0 specification (OpenAPI 2.0 is not supported).
  • Not all validation errors or warnings will have an AI fix that can be applied. For example, AI fixes for x-ibm related issues are not returned.

Using the API Assistant to generate AI fixes for your OpenAPI 3.0 validation errors

Use the API Assistant while creating or editing an API definition in API Manager. The API Assistant validates your API with the OpenAPI 3.0 specification, and suggests AI fixes for any validation errors. You can then choose which fixes that you want to apply to your API definition.

  1. Log in to IBM® API Connect Enterprise as a Service using a Basic or Advanced subscription.
  2. In API Manager, click The Develop icon, which is an outline of a pencil in white on a black background. Develop.
  3. Select an OpenAPI 3.0 API, and click its link to edit it.
  4. On the Develop page, click the source view icon, which is a small grey square containing two angle brackets that enclose a forward slash to work in the Source view.
  5. Click the AI icon, which is a small grey, square containing the letters AI and an arrow in black to open the API Assistant panel.
  6. In the API Assistant panel, ensure that the Specification validation errors tab the specification validation errors tab icon, which is an outline of a page with a small check mark is selected.
  7. Click Validate AI to run the your API through the OpenAPI validation specification.
  8. If validation errors are detected in your API document, and they can be fixed by the API Assistant, the suggested fixes are displayed.
    Note: Not all validation errors or warnings will have an AI fix that can be applied.
  9. For each suggestion, you can click Fix to incorporate the fix into your API, or you can click Ignore to ignore the fix.

    To quickly accept all suggestions, click Apply fixes.

  10. Remember to Save the updated API definition when you're finished.

Example: Enhancing the sample Test error API

In this example we're using a Test error API to show the flow through validating an API with AI, reviewing the suggested fixes, and applying those fixes. You can follow the steps through with your own API.

  1. Log in to API Connect Enterprise as a Service by using a Basic or Advanced subscription.

  2. In API Manager, click The Develop icon, which is an outline of a pencil in white on a black background. Develop to open the API development page, and then ensure that the APIs tab is selected so you can view your APIs.
    Open the Develop page

  3. Select an API of Type OpenAPI 3.0 (REST), and click its Title to edit it.
    Edit an OpenAPI 3.0 API

  4. The Design page opens to the Form view. Click the source view icon, which is a small grey square containing two angle brackets that enclose a forward slash to work in the Source view.

    API Assistant is easier to use when you can see the source code for your API.

    Screen shot of the API design page in form view, with a highlight around the source view icon.
  5. Click the AI icon, which is a small grey, square containing the letters AI and an arrow in black to open the API Assistant panel. Ensure that the Specification validation errors tab is selected.
    Screen shot showing the API Assistant panel, with the specification validation errors tab open.
  6. In the Specification validation errors tab, you can click the AI explained icon, which is the outline of a small black square, containing the letters AI to learn more about how the API Assistant uses AI to quickly resolve your OpenAPI syntax errors.
    Screen shot showing the AI specification validation explanation pop-up.

    Click the AI explained icon, which is the outline of a small black square, containing the letters AI again to close the pop-up.

  7. Now click Validate to validate your API with the OpenAPI 3.0 specification, and see if any AI fixes are identified.

    If errors are found, and they are fixable by AI, the API Assistant returns a list of suggested fixes.

    Screen shot of the AI recommendations for specification validation errors.

    Notice the following changes to the display:

    • The Specification validation errors tab displays a list of the specification errors that the API Assistant has found. With the total number of errors found displayed at the beginning of the panel.
    • While the API Assistant panel is open, the API source code is in read-only mode to prevent accidental updates. When you close the panel, the code becomes editable again.
    • If a suggested AI fix is available for the error, the fix displayed in the Specification validation errors tab with Ignore and Fix options. The suggested fix is also displayed in the source code, directly underneath the original error.
    • If the error does not have an AI fix, the error is displayed with a validation error icon the validation error icon is a small red dot containing a white backslash.
  8. When you're ready to accept or decline the suggested fixes, the following options are available:
    • To quickly accept all of the suggested fixes, click Apply fixes.
    • To accept or decline individual fixes, click Fix or Ignore in each suggestion.
    • To run the validation again, click Regenerate all icon to see the latest specification errors and AI fixes.

    As you work through the suggested fixes, note the following behavior:

    • Any fixes that you apply are added to the API definition, but the definition itself is not saved until you click Save in the API page header.
    • Before saving, you can continue to edit the API, and run the validation again to regenerate the suggested fixes.
    • When you click Save, your own changes and all applied fixes are saved; however, any suggestions that you did not apply are lost.
    • If you navigate away from the API Design page before applying a fix, that fix is lost.
  9. To close the API Assistant panel, click the API assistant panel close icon.

  10. If you want to return to the Form view, click the Form view icon.

    In the sample API, you can see that the suggested AI fixes have been applied, and that the specification status is now green.

    Screen shot of the sample API with all errors fixed.
  11. Remember to click Save to save your updated API definition.