AI-assisted API Design 🤖🧑‍🎨

My experience working alongside ChatGPT to generate OpenAPI specs.

As part of a client job (as a newly-minted freelancer!) I got, I needed to design an API. I decided to write an OpenAPI spec. I’m so used to gRPC that looking at the OpenAPI JSONs and YAMLs doesn’t “gel” well in my brain, but I do know the basics of API design. And, well…

With that in mind, and since the project itself revolves around LLMs, I decided to write the spec together with ChatGPT. It went pretty well, so here are my thoughts and lessons learned.

The Initial Prompt

I started writing my own prompt, and this is what I came up with:

You’re an API designer for a project that uses OpenAPI as the API spec language. You need to write an OpenAPI spec in YAML that describes a RESTful API. For every endpoint, be sure to include a summary, a description, the request body, and example responses for success and for errors. Be as concise as possible. Try to answer will minimal creativity and maximum strictness.

The API needs to include: …

And then a list of endpoints and what they should do. I can share one, but not all the details. This is not an open-source project.

I will share one API endpoint which is not confidential:

1. /status/{component} API endpoints that show the status of various components in the system (such as server, database, and integrations).

I got exactly the response I wanted, but the response was cut off, it was simple to fix. I just needed to ask for more:

Only AFTER the fact I remembered I heard about a tool that does exactly that, promptperfect. I ran my original prompt through it and this is the result:

As an API designer using OpenAPI as the spec language, your task is to write a
concise YAML file that describes a RESTful API. The API should include three
endpoints:

1. /status/{component}: This endpoint should display the status of various
components in the system (such as server, database, and integrations). Please 
provide a summary and description for this endpoint.

2. ...

For each endpoint, please include example responses for success and error cases,
along with relevant request body information where applicable. Your response
should adhere strictly to OpenAPI specifications while still being clear and
informative for potential users of the API.

Iterations

After the initial spec was generated, I pasted the file to VSCode and used the OpenAPI extension to validate it. It only had 2 errors, which I fixed manually. Great starting-off point!

Then, I needed to add to and improve the spec. I asked the bot to help me with that as well.

Creating servers

So simple! Why would I remember the syntax?

Me: Please create a “servers” section with two servers:

1. Local: the URL for that should be localhost:8080
2. Production: the URL for that should be …

The AI: Sure, here’s an updated OpenAPI spec with a “servers” section that includes two servers, one for local development and one for production:

servers:
  - url: http://localhost:8080
    description: Local development server
  - url: https://...
    description: Production server

DRYing up the spec

I wanted to reduce duplication, so I asked the bot to create OpenAPI components for me based on the responses. This was my prompt:

To avoid duplication, extract common structures to a “components” section in the OpenAPI spec. Don’t print the entire spec - just the components section.

It did a pretty good job, but I had to replace the references manually. This was a good chance to read through the API and make sure it makes sense.

In hindsight, I should have used prompt perfect here as well. When given my prompt this is what it gave back:

Your task is to extract the common structures of an OpenAPI specification into a “components” section. Please provide a clear and concise response that includes only the components section, without printing the entire spec.

The components section should include reusable objects such as schemas, responses, parameters, examples, headers, and security schemes. These objects should be defined once in the components section and referenced throughout the rest of the spec where they are needed.

Please note that your response should be flexible enough to allow for various relevant and creative ways of organizing and structuring the components section. You should focus on providing a clear and organized representation of the reusable objects in the OpenAPI specification.

But I’m sort of happy I did this part manually and not with the bot, since it forced me to actually read through the spec and find the next issue, which was…

Limiting responses to Enums

Me:

Please add the list of possible status for components to the Component component.

But ChatGPT only added it to the description, as if anyone’s going to read it. Ugh. This part felt like the AI was getting tired 😅

I should have been more specific. So I combed through the documentation and found what I needed: Enums.

Please use an “enum” for the values of status instead of just the description. Them, update the endpoint…

And the enum was generated correctly.

Summary

This went really REALLY well, and I don’t think I’ll write manual API specifications in the future. It saved me a ton of time.

There are two things I would have done differently:

1. Use prompt perfect for the initial prompt.
2. Validate that everything is considered “best practice”. For example, not using components and references in the first place is bad for maintainability and using Enums to limit the possible values of a field is better than just documentation.

I’m really happy with the result, and I’m looking forward to using this again for other projects.

Cover Image generated with NightCafe 🤖