Before we create an OpenAPI specification, let’s ask the API Agent if we have one already: 

There are a couple of draft and published APIs already within our API Connect Provider Organization, but none of these are what we are looking for... so let’s see how the API Agent can help us create one. 

A great start! It has generated an initial OpenAPI Specification document. Let’s download and review the document in our vscode workspace. 

Wow! The generated spec contains schemas for book, author, publisher, and genre. It also contains CRUD operations (paths) for each of these schemas – it even has correct JSON Pointer References within these operations to their corresponding schemas, to ensure the integrity of the relationships. Pretty good! 
 
Upon closer inspection, it just seems to be missing a dedicated operation for searching for books. This is why it is important to review all AI-generated artifacts before using them! Let me complete my API-first design and add that in. 

Ok, I’m good with the document structure now but wouldn’t it be great if the API documentation was a little better and I had better descriptions and examples in the API. Time to engage the API Agent's API enhancement capabilities.  

2. Enhance the API Specification 

Thats now much improved from the previous draft and I really like this feature in the AI Recommendations panel where I can just select the descriptions and examples I like for the places in the document, I think they are most needed.   

At this point, given that I know I’ve manually updated some things in the document and have added in the missing search operation it would be good for me validate the API spec before going any further forward to check for any syntax or structural errors. Let me validate the document using the agent and see what it finds.  

I’m glad I did that, the agent has found an issue with the document structure. I’m not completely sure how to fix that issue myself I wonder if the agent can do that for me.  

3. Validate and Remediate the OpenAPI Specification 

Excellent, by using the auto-correct agent it has resolved the validation error for me and now I can see how I could have fixed it myself if I ever bump into this issue again.   

At this point I think I'm ready go and do some coding to bring this API to life, except I know that my company would never allow me to publish this API as-is. It's unlikely to comply with all of our corporate security and governance policies - not to mention the fact that it probably isn't following some of our enforced mandatory API best practices and styling guides. This could take a while.
Hang on - I wonder if the Agent could save me some time here. I think I saw in the documentation that there is a governance rule remediation feature. Let me try that out.

Ok, now we’re talking. I can see that my document has got some security issues in the spec when I run the OWASP top ten security ruleset against the API. t seems like from the suggested quick actions in the Agent that it has the capability to remediate the problems. Let’s try that out.

That’s some really interesting and in-depth detail about the issues it has found and the recommended resolutions for them. I really like the way I can accept and apply the fixes directly in the editor itself. This all feels very intuitive. I think I’ll accept them all as I like the recommendations I’m getting.

Ok, so that’s the OpenAPI specification designed and implemented to a really high-quality standard. I should have no problem now in reviewing this with the compliance team to get my API published and out into our customers hands. 

Now time to get coding the application. Let me use the agent to generate the foundation of my Bookshop app based on the specification we’ve just built together.  
 
4. Generate application Code 

Nice! The Agent has provided a zip file of generated code based on my spec. This is going to save me lots of time getting my application up and running.

I like the way the project is structured - it has divided-up the model objects representing my OpenAPI schema objects, and the APIs representing my OpenAPI path operations. I wonder how to get started with the code here. 

This README is exactly what I needed to take me through what I need to do to get the project set up as well as testing out the application quickly locally.  

5. Deployment time

I’m happy with some of the local testing I’ve been doing so let me Deploy the application now using the API Agent and see how things look when the application is deployed on a remote host.  
Wow, this really streamlines the deployment for me, and I like how I can query the status of my application at any point to monitor how the deployment is progressing.  

 
I’ve now got the URL of the deployed application so I can update the server URL in the OpenAPI which I want to start managing and making accessible via APIConnect.  

6. Publish the OpenAPI Specification to APIConnect 

This is great, I can also use the agent to manage the lifecycle of my newly created API. Let me create a Draft API and then publish it to the APIConnect gateway.

Awesome, my API is now published and deployed on the APIConnect gateway. The agent has also created a client subscription for me so I can now share these credentials with my team so they can review and give me feedback on the application I’ve just built with the agent.      
 

A quick test of the published API using the client subscription credentials shows that everything is working as expected. This is really outstanding, how unbelievable straightforward and fast this whole process has been. Hard to believe that in just a number of minutes I’m now looking at my running Bookshop application with some really high quality, enterprise grade artifacts created in APIConnect along the way. 

For details of all the set up and feature capabilities of the API Agent see the following documentation:
Using API Agent in IBM API Connect