Using the API Assistant for error remediation

You can use the specification validation error component of API Assistant, to analyze your OpenAPI 3.0 specification, and generate potential AI fixes for any validation errors. Thereby 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.

How to use 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 the 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 Premium subscription.
  2. In API Manager, open an OpenAPI 3.0 API that you'd like to edit.
  3. In the Design tab, 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.
  4. 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.
  5. 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.
  6. Click Validate to run your API through the OpenAPI validation specification.
  7. If validation errors are detected in your API, 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. For example, AI fixes for x-ibm related issues are not returned.
  8. 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.

  9. Click Save to save the updated API definition.

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 the OpenAPI specification, reviewing the suggested AI 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 using a Premium subscription.

  2. In API Manager, click the Develop icon (which is a small black square containing an outline of a white pencil) 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 in 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 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 is 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.