An OpenAPI bot to help you understand REST APIs

Chat with our bot to get up to speed with a Web API. Quickly discover what you can do with the API without having to go through all its documentation pages.

OpenAPI Bot is implemented using Xatkit, a generic and extensible platform for developing chatbots. OpenAPI is an open source project. Check our GitHub repository.

This bot is part of a collection of projects that aim to facilitate the discovery, composition and understanding of web APIs: Open Data for All project.

HOW IT WORKS

LOAD THE API

Just enter the URL of your OpenAPI definition to bootstrap the conversation. The bot supports both JSON and YAML. Examples:

• Load the API https://petstore.swagger.io/v2/swagger.json
• Load the OpenAPI definition located at https://petstore.swagger.io/v2/swagger.yaml

ASK A QUESTION

Ask a question regarding what you want to know. OpenAPI bot will provide you information about the API. Examples:

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

ASK A COMPLEX QUESTION

OpenAPI bot relies on a set of heuristics to provide advance details which are not visible at first glance. The supported requests so far are:

• 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?

I want to build a similar bot, how is this OpenAPI bot implemented?

OpenAPI Bot is built with Xatkit, a flexible multi-platform (chat)bot development framework. Xatkit comprises three Domain-Specific Languages (DSLs) allowing the definition of different components of a chatbot, namely: Intent DSL, which defines the user inputs through training sentences, and context parameter extraction rules; Execution DSL, which defines how the bot should respond to the matched intents; and Platform DSL, that details the available operations and actions available to the bot (e.g., sending a message, querying a database, etc) depending on the platforms the bot interacts with. Platforms are provided by Xatkit itself.

These languages are complemented by an execution engine that takes care of the deployment of the bots by registering the defined intents to a given NLP engine (DialogFlow in our case), and manages their execution.

Figure 1. A snippet of the definition of GetOperationByName intent.

Figure 1 shows a snippet of the OpenAPI Bot definition². The bot defines a set of intents representing typical questions and navigation queries related to an OpenAPI definition. Figure 1.a shows the intent GetOperationByName, which includes training sentences to get an API operation using its name. The intent creates the Operation context containing the operationName parameter which is extracted from the user input. Our bot uses two Xatkit platforms: the ReactPlatform, a platform that receives user inputs and sends messages through a web-based component, and the OpenAPIPlatform, a custom platform we created to manipulate OpenAPI definitions. The OpenAPI Bot’s execution model binds the specified intents to the platform’s actions. Figure 1.b shows a snippet of the execution model containing the rule to execute when the intent GetOperationByName is matched. This rule first invokes the GetOperationByName action from the OpenAPIPlatform, then checks the returned value to display either the requested operation or an error message if it does not exist.

Figure 2. OpenAPI Bot architecture overview.

Figure 2 shows an overview of the key components of the OpenAPI Bot. The OpenAPI Bot Definition presented earlier is given as input to the OpenAPI Bot Runtime which is composed of the core Xatkit Runtime (that manages the deployment and execution of the bot), as well as the OpenAPI Runtime that contains the concrete implementation of the OpenAPI Platform’s actions. To do so, it relies on the OpenAPI Modeling SDK [3], our model-based framework to manipulate OpenAPI definitions.

Comments

[george-nelson]

Love this bot, is it available on Microsoft Teams?

[Jordi Cabot]

Right now, it's only available with a react widget as front-end. It should be easy to port it to Slack (as Slack is another one of the platforms Xatkit natively supports) but for Microsoft Teams the only "easy" option right now would be to go through Zapier