Everyone talks about ChatGPT - social media is full of it. But while most people seem to use it either for creating social media content or for writing source code, I wonder if ChatGPT can help me do some API design?
API design is a crucial step in the development process of new APIs, as it lays the foundation for the functionality and behavior of an API. The OpenAPI Specification (OAS) is a widely-used standard for describing APIs, which makes it an important tool for API designers. However, creating an OAS document can be a time-consuming and error-prone process.
When I have created an API design in OAS, the next step is usually building a mock of the API as a quick prototype. Why? API prototypes allow for getting tactile feedback from people using the API. Prototypes allow getting the feedback early - before considerable time and money have been spent on creating a real implementation. Prototyping is about reducing time, energy and cost to first API-consumer feedback.
If ChatGPT could automate the process of creating an OAS document, it could help make this process faster and more accurate. In this blog post, we will explore how generative AI can be used to create API designs in the OAS language and discuss the advantages and disadvantages of this approach.
Let’s see how well this approach works on a practical example, where we need to build a new API to expose data from Customer Relationship Management (CRM) software.
To start with, I write 8 words into the ChatGPT console:
write an OpenAPI Spec for a CRM API
And here is what I got: A simple but usable API spec for a CRM API!
I let the output of ChatGPT run through my first impressions check: It looks like proper OAS code. ChatGPT seems to have “understood” the domain of CRM, as it correctly designed a customers resource as a central element for the CRM API, and it seems to “understand” what APIs do, as it designed various HTTP methods (GET, POST, PUT, DELETE) for interaction with the resource. It even provided a sensible list of parameters for each of these methods. I am quite impressed.
But is the syntax of the generated OAS correct? Let’s copy and paste the code into SwaggerUI. And here we see the first syntax errors (see the picture below in the red box). These errors are annoying – but nothing dramatic, and they are quickly fixed.
API Prototyping
The next step in the API design lifecycle is creating an executable version of the API. Its purpose is to get some tactile feedback from users on how the API behaves and how useable it is. This typically means creating a prototype from the API spec. These prototypes can have various degrees of fidelity
- In the simplest case, the prototype is a low-fidelity mock that is only capable of serving static responses, independent of the input that was sent. Code for such mocks can be generated from an OAS and the included response examples.
- A slightly more advanced prototype is dynamic and can process the API request and its parameters to some degree and produce appropriate responses. However, building such dynamic mocks involves some work.
Let’s push the limits of ChatGPT and let it create a simulation – not by producing the code, but by simply asking it to simulate the above API in operation and make up some example data on the fly and return it in the proper format.
Here is my interaction with ChatGPT:
It took me two attempts until I found a way to tell ChatGPT what I want. But the second attempt gave me exactly what I expected: A dynamic prototype of the API defined in OAS. It understood my curl command, read the parameters from the request and produced a JSON response that now only matched the definition of the data structure defined in OAS, but the response values also matched the criteria defined by the input parameters.
Test Cases
As good API designers we don’t just throw the OpenAPI spec over the wall for implementation in a microservice. We create a couple of test cases for the developers building the microservice implementing the API. Let’s see how ChatGPT can support us with this task.
While ChatGPT did produce a unit test, I did not see a big advantage in using it compared to the alternative: a test code generator for OpenAPI Specs (see here for a list OpenAPI.Tools - an Open Source list of great tools for Open API).
Conclusion
For this blog post, I have experimented a bit with ChatGPT. What impressed me the most, is ChatGPT’s capability of creating an (almost correct) OAS document for a random topic. This can save a significant amount of time compared to manual creation.
But don’t worry – it won’t make you redundant as an API designer! It will make us more efficient in some cases, allow us to think more about the bigger picture (and bigger picture problems), and take care of some repetitive tasks. Also keep in mind, we have just worked on toy examples for APIs, which might be representative only for the first prototype of a new API that you built – not for a complex, production ready API.
An important aspect of using ChatGPT for API design work is knowing when to apply it as a tool that can help you get a task done quicker and when to just work the traditional way. So we as a community should collaborate and collect experiences on using ChatGPT for API design work. I want to invite you to post your personal findings in the comments.
There are certainly lots of potential use cases for API design, all around the API lifecycle. In this article, I have just been able to scratch the surface. And I invite you to list all the other cool use cases for ChatGPT in API design in the comment section below. Let’s build a big list of use cases together here. Who has even better/cooler use cases? Let’s post all your ideas and experiments here and learn what this new technology can do for us. ChatGPT for API Design
This article is part of the TECHniques newsletter blog - technical tips and tricks for the Software AG community. Subscribe to receive our quarterly updates or read the latest issue.