Using ChatGPT to Reinvigorate APIs
In this post, we’ll see how ChatGPT can be used to reinvigorate APIs by creating an OpenAPI specification for an existing API that has existing documentation.
Introduction
ChatGPT, developed by OpenAI, has generated attention for its natural language processing capabilities. ChatGPT is based on machine learning techniques such as Generative Pre-trained Transformer (GPT) architecture which is part of Large Language Models (LLMs).
Application Programming Interfaces (APIs) underpins modern software development, enabling communication between different systems. Legacy APIs often lack standardized documentation, and versioning controls leading to outdated information, maintenance challenges, and slower API usage uptake.
Newer APIs often adopt standards such as OpenAPI specification which is defined by the OpenAPI Initiative to describe how the APIs work in machine-readable documentation. Using an OpenAPI specification to describe an API provides consistency across APIs, the ability to document the API, a contract on how to use the API, the ability to generate code stubs to consume and produce APIs, and API versioning. These features enable quicker API development, quicker uptake of API services, and a reduction in API maintenance.
Let’s see how ChatGPT might be used to reinvigorate APIs by creating an OpenAPI specification for an existing API with existing documentation. For our purposes, the API that will be used is “Where the ISS at?” which returns information about the International Space Station. The “Where the ISS at?” documentation can also be found on the Wayback Machine — just in case the main website disappears.
Full file details for ChatGPT questions and responses used in the article can be found in the GitHub Repository - ChatGPT OpenAPI specification.
Generating an OpenAPI Specification with ChatGPT
Using ChatGPT version 3.5, we asked the following:
ChatGTP OpenAPI specification result
The results that ChatGPT produces are non-deterministic, which means the same question submitted at different times, will most probably produce different results. While creating this article, the above question was asked multiple times on ChatGPT which returned different but “similar” results for the questions. Repeating the above question will likely create different results from the ones below.
Due to this, ChatGPT isn’t something that could easily be used within an automated CI/CD pipeline as the results aren’t likely to be the same. This non-deterministic nature also means at times bits of the OpenAPI specification didn’t appear correctly in one result but did in another. Manually comparing the different results and combining them manually might be another approach to creating an initial OpenAPI specification.
Taking the generated OpenAPI specification from ChatGPT, the next step was to validate the results. The OpenAPI ecosystem has many tools that can validate an OpenAPI specification. One of those is Kong Insomnia.
Insomnia includes a default linter that can check to see how well the OpenAPI specification is formatted compared to the specification. The Insomnia lint ruleset can also be custom-defined within Insomnia if a certain style needs to be adhered to.
ChatGPT OpenAPI specification in Kong Insomnia
The ChatGPT-generated OpenAPI specification has 2 errors and 11 warnings. The 2 errors are related to the parameters not being identified correctly, this can be fixed by changing /coordinates/{lat,lon}: to /coordinates/{lat},{lon}:
Re-generating an OpenAPI Specification with ChatGPT
To tackle the warnings from the previous ChatGPT results, let’s apply a custom naming style for operations and use a specific OpenAPI specification version. The ChatGPT question was rephased to:
ChatGPT’s second OpenAPI specification response in Kong Insomnia
This second ChatGPT-generated OpenAPI specification has 3 errors and 6 warnings. As before, 2 errors are related to the parameters not being identified correctly. This can be fixed by changing /coordinates/{lat,lon}: to /coordinates/{lat},{lon}:
Correctly indenting the contact information removes the other error and contact missing warning.
To fix the global tags missing, the following was added:
The second generated OpenAPI specification successfully linted in Kong Insomnia
Multiple OpenAPI Specification versions
An advantage of using an OpenAPI specification is that it can be versioned. In this article, several different OpenAPI specifications have been created which build on top of each other. ChatGPT could be used to create a rough and ready initial specification version that is shared with developers. Then over time, updated specification versions could be released. These different versions can be managed in a developer portal to enable quicker API development, quicker uptake of API services, and a reduction in API maintenance.
Different “Where the ISS at?” versions in the Kong Konnect Developer Portal
Summary
ChatGPT can generate an almost complete and working OpenAPI specification, but in both cases, “minor” issues needed to be addressed which were identified using an OpenAPI specification linter. While the fixed version of the OpenAPI specification is syntactically correct, the OpenAPI specification can be further refined for example updating the description fields, adding default values for parameters, validating parameters, etc. so it is more useful for developers.
The above work was based on one API that is well-documented in something other than an OpenAPI specification. Applying ChatGPT to an API with minimal documentation may have completely different results.
ChatGPT is an option to consider when an API has some existing documentation and a quick initial cut of an OpenAPI specification is required with minor changes. Expecting a fully complete generated OpenAPI specification with a repeatable output from ChatGPT using the above approach in 2023 is unrealistic. But in 5 or 10 years, who knows how far things will have progressed?