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.
- Log in to IBM® API Connect Enterprise as a Service using a Premium subscription.
- In API Manager, open an OpenAPI 3.0 API that you'd like to edit.
- In the Design tab, click
to work in the Source view.
- Click
to open the API Assistant panel.
- Ensure that the Specification validation errors tab
is selected.
- Click Validate to run your API through the OpenAPI validation specification.
- 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. - 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.
- 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.
- Log in to API Connect Enterprise as a Service using a Premium subscription.
- In API
Manager, click
Develop to open the API development page, and then ensure that the APIs tab is selected so you can view your APIs.
- Select an API of Type OpenAPI 3.0 (REST), and click its
Title to edit it.
- The Design page opens in Form view. Click
to work in Source view.
API Assistant is easier to use when you can see the source code for your API.
- Click
to open the API Assistant panel. Ensure that the Specification validation errors tab is selected.
- In the Specification validation errors tab, you can click
to learn more about how the API Assistant uses AI to quickly resolve your OpenAPI syntax errors.
Click
again to close the pop-up.
- 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.
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
.
- 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
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.
- To close the API Assistant panel,
click
.
- If you want to return to the Form view, click
.
In the sample API, you can see that the suggested AI fixes have been applied, and that the specification status is now green.
- Remember to click Save to save your updated API definition.