API Design Assistant

Designing APIs is a crucial part of the API development lifecycle. With API Manager, you can easily create APIs using natural language through the API Design Assistant. This AI-powered tool requires no prior coding or API knowledge, allowing you to design REST, GraphQL, and Async APIs effortlessly by transforming your requirements into API specifications.

Info

This feature is currently in the experimental stage and is exclusively for REST APIs, GraphQL APIs and Async (WebSub, WebSocket, SSE) APIs. If you require SOAP APIs or AI APIs, regrettably, this feature is not available for use at this moment.

Follow the steps below to get started with the API Design Assistant:

Tip

If you've previously registered your environment for the API Chat or Marketplace Assistant, you can skip Step 1 and 2 by utilizing the same credentials for the API Design Assistant. Otherwise, complete Step 1 to register your on-premise environment.

Step 1 - Sign in to AI Subscription Portal

Warning

Information in the AI Subscription Portal will be stored in the United States.

1. Navigate to the AI Subscription Portal using the following URL: https://ai-subscriptions.wso2.com.

2. Register for an Account.

• Click Register.
• Enter a valid email address and click Register.
• Check your email inbox and click Complete Account Creation.

• Provide an organization name (make a note of this, as it will be required for every login) and create a secure password.

• Login to the AI Subscription Portal.

• Click Sign In and enter your organization name.

• Enter your email address and password.

Step 2 - Create a key by subscribing

1. On the main landing page, click New Subscription.

   

2. Select wso2am as the product, enter an appropriate name, and create the subscription.

   Info

   Users can create multiple subscriptions for different on-premises environments and manage them through the portal.

   Warning

   Do not use the same key for different environments or products. Each key is used to differentiate environments when accessing AI services.

   

   Warning

   Users can revoke and regenerate keys for any subscription, as well as delete subscriptions. Please perform these actions with caution, as they will immediately invalidate any existing keys in use.

Step 3 - Configure API Manager

1. The following configuration change must be done in the <API-M_HOME>/repository/conf/deployment.toml file. Update the [apim.ai] config by providing the on-premise token obtained from Step 2. Also, be sure to update the endpoint field as below.

   [apim.ai]
   enable = true
   endpoint = "https://dev-tools.wso2.com/apim-ai-service/v2"
   key = "<use key that you generated>"
   token_endpoint = "https://api.asgardeo.io/t/wso2devtools/oauth2/token"
   

2. Restart the API Manager.

Step 4 - Engage with the API Design Assistant

Now that your environment is configured, you're ready to interact with the API Design Assistant. Utilize its capabilities to design your APIs.

1. Sign in to the WSO2 Publisher Portal (https://<hostname>:9443/publisher)

2. On the landing page, click on the ‘Create API with AI’ Button at the bottom of the page

   

   or if you have already created an API, click the ‘Create API with AI’ Button on the top left to navigate to API Design Assistant.

   

3. Send a query to the Assistant to create a specific API of your choice, such as "Create an API for a university." Also it is possible to enter additional queries to modify the generated specification further. You can use queries such as the following:

   • Extend /GET students to also return the total number of students (only for REST APIs)
   • Include courses as well
   • Summarize this API

4. View the resources via the Swagger UI. When the generated specification is an OpenAPI spec, the Swagger UI will be displayed by default, visualizing the REST API’s resources. You can select a resource path to view its details.

   Note

   If the generated specification is not an OpenAPI spec, the Swagger UI will not be visible.

   

5. View the generated specification by toggling "View Source" located in the top-right corner.

   Note

   For non-OpenAPI specifications, the generated spec will be displayed by default.

   

6. Change existing resources by typing ‘/’ in the input field and selecting the resource you want to modify from the dropdown menu. After generating the updated OpenAPI spec, users can navigate to the modified resource in the Swagger UI to view the changes.

   Note

   For non-OpenAPI specs, typing ‘/’ will result in a “No resources” message in the dropdown menu.

   

   

7. Improve your API’s structure and functionality by making modifications to endpoints, parameters and response formats.

   

8. Ask questions to learn what your API does, how it works and the information it provides.

   

9. Click the 'Create API' button in the bottom right corner and confirm by selecting 'Yes' to launch the API Creation Wizard. Here, you can refine essential metadata details, including the API's name, version, and context. Once satisfied, click 'Create' to create the API in the Publisher Portal.

   

10. Explore the API’s details on its overview page.

    

FAQ

1. Why is this an experimental feature?

The API Design Assistant is labeled as an experimental feature because it represents innovative technology that is still under development. AI technology is rapidly evolving with significant enhancements in large language models and the introduction of increasingly efficient chips, and we are integrating the latest advancements to enhance our capabilities. Rolling out new features as experimental underscores our commitment to innovation, and as we continue to refine them, we are focused on enhancing their performance and reliability based on user input and ongoing development efforts.

2. What types of APIs are supported?

The platform supports REST, GraphQL and Async (WebSub, WebSocket, SSE) APIs, allowing users to design and modify these API types efficiently. However, it does not support AI APIs or SOAP APIs.

3. Why did I lose my chat history after I logged out or exited API Design Assistant?

Your chat history will be lost after logging out or after a period of inactivity of 15 minutes, as per the design of the application.

4. I am getting this error response: Apologies for the inconvenience. It appears that your token is invalid or expired. Please provide a valid token or upgrade your subscription plan.

This message suggests that your on-prem key is not valid or it is expired. You can request an extended trial period or you can upgrade your subscription plan so that you can seamlessly use API Design Assistant.

5. I am getting this error response: Apologies for the inconvenience. The request has timed out. Please try again.

This message indicates that the response took longer than expected to generate. Kindly resend the same query and try again or reach out to the administrator for assistance in resolving the problem.

6. I am getting this error response: Apologies for the inconvenience. It seems that something went wrong with the API Design Assistant. Please try again.

This message signifies that an unexpected error has occurred. It could be due to various reasons such as server issues, network problems, etc. Kindly resend the same query and try again or reach out to the administrator for assistance in resolving the problem.