"API testing is a type of software testing that involves testing application programming interfaces (APIs) directly and as part of integration testing to determine if they meet expectations for functionality, reliability, performance, and security. Since APIs lack a GUI, API testing is performed at the message layer."
Wikipedia API Testing definition
It is sometimes difficult to test and verify the functioning of API calls in Voiceflow, indeed the Integration block is not a tool to debug your API calls, this work must be done upstream not to add a risk of errors to your project.
In this article we will use the Airtable API, this will allow us to test GET and the POST requests as well as the use of a token to authenticate us when calling the API.
If you need more information about using the Airtable API in your projects you can read the following post on our forum: Manage user preferences, store and retrieve information from an Airtable database
LET'S GET STARTED
First of all we will have to download Postman, this tool offers a free version and is available for Windows, Mac and Linux.
After downloading, installing and running Postman, you should find yourself on an interface like this:
So we will start by creating our first collection (see a collection as a set of requests available for the same API). As we are going to test the Airtable API, let's call our first collection "Airtable".
As Postman points out, our collection is empty. We will have to add requests to start the tests.
GET INFORMATION ABOUT YOUR API
Unless you are using a custom API, you should find the different requests available in the API documentation that you want to use in your project.
As for this example we will use Airtable, go to your account and create a simple database, here is the one I will use for this article.
Again, if you need more information about using the Airtable API in your projects you can read the following post on our forum: Manage user preferences, store and retrieve information from an Airtable database
In Airtable, the API documentation is available from the help menu.
The first thing we will have to do after studying the documentation will be to authenticate ourselves for each call to the API. This will be done thanks to the API key you generated from your Airtable account.
If you do not see your API key in the examples in the Airtable documentation, remember to check the show API key box.
As the documentation indicates, we have two ways to authenticate ourselves. We can use our key in a header (recommended) or with the
api_key query parameter.
"You can authenticate to the API by providing your API key in the HTTP authorization bearer token header. Alternatively, a slightly lower-security approach is to provide your API key with the
All API requests must be authenticated and made over HTTPS."
Now that we know how to authenticate our API calls, let's move on to the first test, get the data in our database with a GET request.
So let's go to the List records section of the USERS TABLE to get the request we will have to use.
On the right panel, Airtable presents us with an example of a request with the url and header to use to list the records in our database.
This is exactly what we need to create our first request in Postman.
First copy the url displayed under EXAMPLE REQUEST
CREATE YOUR FIRST REQUEST IN POSTMAN
In Postman, click on Add requests, use List records for the Request name and click on Save to Airtable (or the name you give to your collection).
You can also add a request via the menu by moving your mouse over your collection and then clicking on the three dots.
In the "List records" tab of the request you have just created, you can paste the url in the "Enter request URL" field.
The default method selected is GET
which is perfect because the documentation told us that for this call we must use the GET method.
Hit save and click on the Send button.
After a short time, you will get the answer from the API.
"message": "Authentication required"
Indeed, as we have seen before, each call to the API must be authenticated.
So let's go back to the Airtable documentation and copy the part necessary for authentication.
Authorization: Bearer keyY6PccqvLBwFzSi
Let's now add this header to our Postman request.
Click on the Headers section of your request, add Authorization as key and Bearer followed by your API key as value (Bearer keyY6PccqvLBwFzSi for my database).
Here is what the headers section of your request should look like in Postman.
Hit Save and Send again, this time you should get the desired result.
"Name": "Nicolas Arcay Bermejo"
Well done! You have just created and tested your first request in Postman.
ADD A NEW POST REQUEST TO YOUR COLLECTION
Now that we have created our Airtable collection and our first List records request in Postman, we are ready to add a new request and this time, we will focus on the Create a record request.
As before, let's start by studying the Airtable documentation. In the Create a record section, here is what we learn.
So our method is different for this request, we will use POST to send data to the API.
After a quick look at the example provided by the documentation we can see that we will have to add a new header but also some data and the format expected by the API. Finally, the url changed is now https://api.airtable.com/v0/app7YwPYw6GeVcGKE/Users
The Content-Type header
The data to send with the POST method
"Name":"Nicolas Arcay Bermejo",
Let's go back to Postman and to simplify the task, we will duplicate our first request. This will allow us to keep the header information (the Authentication part).
To duplicate our request, move your mouse over List records and click on the 3 dots to display the menu.
Click on Duplicate and rename your new request to Create a record.
As we saw in the documentation, you will have to change the url and method for this API call.
We also need to add the content-type header. Click on the Headers tab and add the Content-Type key with application/json as value.
Last but not least, before testing our new request, we will have to add the data to be created in our database.
Let's take the example of the API documentation, copy it and paste it into the Body part of your request in the raw format.
"Name":"Nicolas Arcay Bermejo",
Before testing your request, edit the data you have just added. Change the Name, ID and Email.
Hit Save then Send.
Congratulations, as you can see in the bottom part (response body) you have just created a new record in your database.
This is one of the advantages of testing your APIs in Postman, for each API call you get the result in the Body tab. This way you can simply check if everything is working as you want but also know the data returned by the API to use them later in Voiceflow.
Finally, if you check your Airtable database you will notice that a new record has been created.
DEBUG YOUR ERRORS IN POSTMAN
Sometimes you can make mistakes in your API calls. As we have seen above for authorization, most of the time you will get a feedback message with a code and/or information about the error.
For this last test we will voluntarily create an error by modifying the data sent to the Airtable API.
In the Body raw source of the Create a record request, delete the s at the end of the word fields.
Save and hit the Send button, it will generate an error and the API will return this information to you.
As you can read, the API warns us of an error in the request data. The fact of having deleted the s to fields in the body made our request invalid and the API warns us of this error. Here the API even provides us with advice:
Check your request data.
Again, this is why it is important to debug your API calls in Postman before using them in Voiceflow.
We used here the Airtable API, very well documented and very easy to access but this is not always the case. Sometimes you will have to try several times, review the documentation to finally get the desired result.
This step must be done before the creation of your project to be sure that you will be able to use your API correctly in Voiceflow.