AI-powered chatbots are gaining popularity across the board. Not only are they more affordable than human agents, but they’re also present whenever you need them. Thankfully, things have come a long way since the days of Clippy, BonziBuddy, and other virtual assistants. Now, chatbots can understand and act on queries better than ever.

So, why not build a chatbot that can answer questions about almost any API? Technically, all it would take is putting a Natural Language Processing layer over an OpenAPI specification. Well, that’s precisely what a team of researchers has done. The result is OpenAPI Bot — and in this article, we’ll review it.

What Is OpenAPI Bot?

OpenAPI Bot is a novel tool that allows developers to learn about web APIs by speaking to a chatbot. The open-source project — created by three researchers from the Open University of Catalonia — was first released on Github in July 2019.

OpenAPI Bot works by consuming an OpenAPI Specification file for the API in question. Since many synchronous web APIs already use this language to describe themselves, OpenAPI Bot is yet another choice on the long list of spec-driven tools for enabling API adoption.

How to Use OpenAPI Bot

The project’s homepage presents a live implementation of OpenAPI Bot: click “Try it out!” and a small chat box will appear on the bottom right-hand corner of your browser. This version of the bot allows you to provide the specification for any API of your choice, although the end goal would likely be for API owners to provide customized bots specific to their dev portals. In any case, here’s what’s involved.

Loading a Specification

First things first, the bot will ask you to provide the OpenAPI specification for your chosen API. Simply enter the URL of the specification — in the form of a JSON or YAML file — and hit return. To keep things familiar, we’ll opt for Swagger’s infamous Petstore API, which is available at https://petstore.swagger.io/v2/swagger.json:

Asking Simple Questions

After a short delay, the bot should inform you that it has loaded your chosen specification. At this point, it’ll be rearing to hear your questions:

But what can you actually ask the bot? According to the developers, OpenAPI Bot supports a handful of simple questions (and requests), such as:

• How do I contact the developer of the API?
• Give me a summary of this API
• Show me a list of paths in the API
• Tell me about the /pet path
• Show me the schema definitions
• Which operations return a Pet?

So far, so good: the bot can locate and extract basic information from the specification. That said, if you know where to look, you can just as easily find this information by delving into the spec itself…

Asking Complex Questions

Where OpenAPI Bot really shines as a proof of concept is in its ability to process complex questions. Here, the developers provide the following three examples:

• Are there operations which use the properties of Pet?
• Are there links between Pet and other definitions?
• Which operations do I need to change if I change the schema Pet?

Unless you want to Ctrl+F your way through every instance of “Pet” in the specification file — and even then, that might not cut it — it can be difficult to know which objects are interconnected. OpenAPI Bot quickly and easily checks this for you:

Building Your Own API Chatbot

If you feel inspired by OpenAPI Bot, the good news is that you can build your own API chatbot with relative ease. OpenAPI Bot itself is built on Xatkit, with all of the code available in the GitHub repository. As a result, all you really need to do is install Xatkit and clone the repository onto your local device.

For tweaks, you’d probably want to hard-code the URL of your API’s specification into the bot. Then, aside from adding more sophisticated questions (and more of them), you might want to integrate the bot with other parts of your developer ecosystem — to distribute API keys or open support tickets, among other such creative extensions.

The Potential for API Chatbots

Although it’s just a proof of concept, OpenAPI Bot demonstrates another way to use your existing API specification: chatbots. However, do API chatbots (based on specification files) really bring anything to the table, or are they just a fun gimmick for your developer portal?

Benefits

Spec-based chatbots definitely have their benefits. They can be a fun and interactive way to extract information from an API specification — that is, if they succeed at understanding the developer’s queries. Additionally, if they can process more complex relational queries, they could save the developer some time trawling through the spec manually. Finally, for more unified developer experience, chatbots can also be extended with an API key, security ticket, or other functionality, creating a one-stop-shop for automated API assistance.

It’s important to note that AI chatbots have already proven themselves in the SaaS world. Usually equipped with support functionality, they ultimately reduce the need for human personnel, leading to a faster (for the end-user) and more affordable (for the provider) support experience.

Limitations

Of course, spec-based API chatbots have their limitations. Besides being able to identify intent from the exact words used in the query (which is a challenge every chatbot faces), they need to be programmed to serve these intents. As a result, for an API chatbot to be useful, the creator has to spend a fair amount of time thinking about the developer’s questions and writing algorithms to extract that information from the spec.

Final Thoughts

OpenAPI Bot is a fascinating proof of concept. By consuming an existing OpenAPI specification file, the tool is able to answer a variety of questions — both simple and complex — about an API. While the idea is still in its early days, there is definitely potential for a tool like this to provide significant value to developers, especially when integrated with other developer portal functionalities.