An OpenAPI bot to help you understand REST APIs
Tags: api, openapi, rest, chatbot
Published: 2020-04-02 15:11:31

Chat with [our bot](https://som-research.uoc.edu/tools/openapi-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](https://xatkit.com/), a generic and extensible platform for developing chatbots. OpenAPI is an open source project. Check [our GitHub repository](https://github.com/opendata-for-all/openapi-bot). 

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](https://github.com/opendata-for-all) project.

<h2>HOW IT WORKS</h2>
<h3>LOAD THE API</h3>
<p>Just enter the URL of your OpenAPI definition to bootstrap the conversation. The bot supports both JSON and YAML. Examples:</p>

<ul>
 	<li><em>Load the API https://petstore.swagger.io/v2/swagger.json</em></li>
 	<li><em>Load the OpenAPI definition located at https://petstore.swagger.io/v2/swagger.yaml</em></li>
</ul>
<img src="https://som-research.uoc.edu/tools/openapi-bot/assets/img/chat1.gif" alt="OpenAPI bot animated GIF 1" />

<h3 class="article-row-content-header">ASK A QUESTION</h3>
Ask a question regarding what you want to know. OpenAPI bot will provide you information about the API. Examples:
<ul>
 	<li><em>How to contact the developer of the API?</em></li>
 	<li><em>Give me a summary of this API</em></li>
 	<li><em>Show me the list of paths in the API</em></li>
 	<li><em>Tell me about the path /pet</em></li>
 	<li><em>Show me the schema definitions</em></li>
 	<li><em>Which operations return a Pet?</em></li>
</ul>

<img src="https://som-research.uoc.edu/tools/openapi-bot/assets/img/chat2.gif" alt="OpenAPI bot animated GIF 2" />

<h3>ASK A COMPLEX QUESTION</h3>
<p>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:</p>

<ul>
 	<li><em>Are there operations which use the properties of Pet?</em></li>
 	<li><em>Are there links between Pet and other definitions?</em></li>
 	<li><em>Which operations do I need to change if I change the schema Pet?</em></li>
</ul>

<img src="https://som-research.uoc.edu/tools/openapi-bot/assets/img/chat3.gif" alt="OpenAPI bot animated GIF 3" />

<h2>I want to build a similar bot, how is this OpenAPI bot implemented?</h2>
OpenAPI Bot is built with <a href="http://xatkit.com">Xatkit</a>, 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: <em>Intent DSL</em>, which defines the user inputs through training sentences, and context parameter extraction rules; <em>Execution DSL</em>, which defines how the bot should respond to the matched intents; and <em>Platform DSL</em>, 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 (<a href="https://dialogflow.com/" target="_blank" rel="noopener noreferrer">DialogFlow</a> in our case), and manages their execution.
<figure><img id="openapi-bot-example" class="aligncenter wp-image-7376 size-large" src="https://modeling-languages.com/wp-content/uploads/2020/03/definition-1024x258.png" alt="A snippet of the OpenAPI Bot definition" width="1024" height="258" /><figcaption>Figure 1. A snippet of the definition of <code>GetOperationByName</code> intent.</figcaption></figure>
Figure <a href="#openapi-bot-example" data-reference-type="ref" data-reference="fig:example">1</a> shows a snippet of the OpenAPI Bot definition<a id="fnref3" class="footnote-ref" role="doc-noteref" href="#fn3"><sup>2</sup></a>. The bot defines a set of intents representing typical questions and navigation queries related to an OpenAPI definition. Figure <a href="example" data-reference-type="ref" data-reference="fig:example">1</a>.a shows the intent <code>GetOperationByName</code>, which includes training sentences to get an API operation using its name. The intent creates the <code>Operation</code> context containing the <code>operationName</code> parameter which is extracted from the user input. Our bot uses two Xatkit platforms: the <code>ReactPlatform</code>, a platform that receives user inputs and sends messages through a web-based component, and the <code>OpenAPIPlatform</code>, 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 <a href="example" data-reference-type="ref" data-reference="fig:example">1</a>.b shows a snippet of the execution model containing the rule to execute when the intent <code>GetOperationByName</code> is matched. This rule first invokes the <code>GetOperationByName</code> action from the <code>OpenAPIPlatform</code>, then checks the returned value to display either the requested operation or an error message if it does not exist.
<figure><img id="overview" class="aligncenter size-full wp-image-7377" src="https://modeling-languages.com/wp-content/uploads/2020/03/overview.png" alt="OpenAPI Bot approach overview" width="1000" height="366" /><figcaption>Figure 2. OpenAPI Bot architecture overview.</figcaption></figure>
Figure <a href="#overview" data-reference-type="ref" data-reference="fig:overview">2</a> shows an overview of the key components of the <code>OpenAPI Bot</code>. The <em>OpenAPI Bot Definition</em> presented earlier is given as input to the <em>OpenAPI Bot Runtime</em> which is composed of the core <em>Xatkit Runtime</em> (that manages the deployment and execution of the bot), as well as the <em>OpenAPI Runtime</em> that contains the concrete implementation of the <code>OpenAPI Platform</code>’s actions. To do so, it relies on the <a href="https://modeling-languages.com/wapiml-web-api-uml/" target="_blank" rel="noopener noreferrer"><em>OpenAPI Modeling SDK</em></a> [3], our model-based framework to manipulate OpenAPI definitions.