From cURL to an extension under 5 minutes!

Photo by Josh Calabrese on Unsplash

We recently announced that you can connect any external system to Watson Assistant. That may not sound like a big deal… but it is, because it’s super easy to do!

In a previous blog, we gave an example of how to connect to a third-party system or service using an API exposed via an OpenAPI spec. This time around, we’ll show how you can easily connect to your own, in-house backend system. It should be even easier than connecting to a third-party system since you’ll already know your API inside and out.

Speaking of which, I’m sure you have a cURL command for your API. So let’s start with that.

In an ideal world, we would be creating an OpenAPI specification directly out of your cURL commands. While there are tools out there to do this, I haven’t found one that does a fully satisfactory job. So instead, I recommend a two-phased approach using Postman:

• First: create a Postman Collection out of the cURL command.
• Second: transform the Postman Collection into an OpenAPI specification.

I chose to use Postman for its ecosystem of built-in tools that are suitable for our needs, such as the conversion of a Collection to an OpenAPI specification. There are, however, many other tools that can serve just as well.

Step 1: Create a Postman collection out of your cURL command

For the purpose of this example, I will use ServiceNow. It is not a first-party API, but it is a third party service that doesn’t have an OpenAPI spec, so it will do for this example.

ServiceNow is a cloud-based software platform for IT Service Management (ITSM) which helps to automate IT Business Management. While they have a variety of features, for the sake of brevity we will focus on their incident management functionality, specifically creating an Incident.

Here is the cURL command, which I obtained from their Table API that manages Service Now tables. For this example, we’ll choose the Incident table.

curl "https://instance.service-now.com/api/now/table/incident" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data '{"short_description":"Unable to connect to office wifi","assignment_group":"287ebd7da9fe198100f92cc8d1d2154e","urgency":"2","impact":"2"}'\
--user 'username':'password'

Now, Go to Postman, create a collection, click on Import, and paste the cURL as shown here:

Save your imported request into the collection you just created.
Since we are using an example from ServiceNow, it doesn’t contain details of your account, hence a few modifications are needed:

1. Replace instance with your ServiceNow instance.
2. Replace username and password with your ServiceNow credentials. To understand where to find those, please go checkout our full ServiceNow example.

You are now ready to test your imported request.

Step 2: Create an OpenAPI specification from your Postman Collection

We are now ready to make a call via Postman. Before you go on, you should verify that your request works after applying the modifications from Step 1.

Your collection is now ready for exporting! Click on *** -> Export

Next, copy and paste your exported Postman into one of the publicly available tools that transforms a Postman collection to an OpenAPI specification. Unfortunately, there is no free online tool that does it all. My workaround of choice was to use https://kevinswiber.github.io/postman2openapi/. Copy the generated openAPI and paste it into swagger.io editor, it will render as:

ServiceNow — Create an Incident OpenAPI specification

A careful look, however, would tell you that this converter doesn’t convert the security details, thus I had to add:

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
   - basicAuth: []

Pro Tip 1: You don’t have to know the syntax, if you use this tool to convert the Postman collection, the security details will be there. Unfortunately, this tool has other limitations, so I personally chose not to use it.

Pro Tip 2: Developers using ServiceNow get a Personal Developer Instance. However, those instances can be reclaimed if you haven’t been active for a while. Therefore, you might want to modify your OpenAPI specification as follows…

Instead of:

servers:
 — url: "https://dev93773.service-now.com"

Add:

servers:
  - url: "https://{instance}.service-now.com"
    variables:
      instance:
        default: dev93773
        description: Your PDI name

Finally, click on File -> Convert and Save as JSON

and you are done. You now have an OpenAPI specification that you can use in your Watson Assistant chatbot.

Step 3: Take your OpenAPI specification for a test drive

The process on how to create an Extension from an OpenAPI specification is documented here. We will use a pre-made chatbot and add to it our extension. A complete guide on how to do this is available here.
After you have set it up, a successful conversation should look as follows:

Concluding Remarks

Hopefully, I’ve proved to you that using Watson Assistant Extensions to connect with your Backend API is just plain simple. It’s a matter of knowing your API well. My focus was on ease of use and speed.

If your API is more complex and the tools I’ve mentioned are not good enough, please note that many other tools exist - they just currently do not offer an online experience or are not free.

You would need to install and run them. If (or more precisely when) other tools surface, I will do my best to upload this blog post. Stay tuned and happy building!