Setting up an API Block to fetch data from external JSON REST APIs.
With Botmock, the ability to bring in live information from different Application Programming Interfaces can trigger different types of use cases and ways to take data, turn them into variables, and utilize them throughout a conversational flow.
Before going through this tutorial, we do suggest that you make sure you understand how to properly use APIs and how to call them. To get started, refer to this helpful tutorial if you are just getting started.
To get started, we need to to first, add our API Block to our flow. Within Botmock, the API Block is considered a "default" block, which means it is not limited by which platform you're using and is available to use at any point in any Flow Project you create.
To use it, simply hit the "+" icon next a content block, and select the API Content Block option. From here, you should see a new API Content Block appear in your editor.
Setting up the API Content Block is when things get a little bit more hands-on. Within the Content Block itself, you have a few options that will work together to allow you to both GET and POST data within Botmock. When adding a new API Block, you will notice right away that it will throw up a message telling you to “Please Setup the API Block. A URL for the request is required”. This message potentially is getting you started in the mindset that you will need a URL endpoint to make the block work.
These are the content block options that are specific for the API Block:
Request Type - Essentially, this is telling Botmock what to do with the URL endpoint. Here, you have the option to select GET or POST, which correspond to fetching data, or posting/creating it somewhere respectively.
Request URL - This is the main piece of the whole puzzle. In this case, setting up a POST/GET request needs to go somewhere, and your URL will be the endpoint to hit in order to make the proper requests.
Request Headers - The Request Headers have to do with how the data is transferred through a URL in the form of the “HTTP” standard, which has to do with how a request should be handled from a URL connection standpoint.
Request Parameters - This becomes more specific to what needs to be done to call and activate the API Endpoint. Parameters essentially to add different elements to a “Payload” that gets sent to a Request URL for something happen. For example, if your API Endpoint requires some security, the header would be a way to set that up. Within the Request Parameters section, you can have a key and its value.
Response Mapping - With the Response Mapping Input, you can make the decision on how to take something out of the response that an API Endpoint/Request URL will return in a JSON output. The two options here are the “Response JSON Path” and Map to Variable. With “Map to Variables”, you can easily tell a Botmock Variable to store a piece of data from the output of the API and carry that around a conversation testing session in Previews and Usability Tests.
Test Response - This is not really an option for any real input, but rather, a way to easily test if your request hits the Request URL properly and returns the data correctly. Once you hit the button, you should be able to see a full response right from within the Content Block itself.
Now that we have ran through the settings, the next step is being able to actually utilize a real REST-based API within the block. In this example, we are only going to use a placeholder API called JSONPlaceholder as an example.
In this example, we are going to simply use the “GET” Request Type to retrieve data from the sample API and store map it to a variable within Botmock. In this example, we don't need to add any Request Headers or Parameters, but what we're doing is hitting the "Posts" endpoint from the JSONPlaceholder API, and asking it to take the first user's ID (1.userID) from the list of Users and Posts that it returns.
Now, we can jump into a step-by-step preview to see how the API block stores the data.
As you can see, the Botmock Preview will make sure to notify you when in the conversation the API is being called (successfully) and from there, the data from the API will automatically save into a variable for your to re-use at any point in the preview session. It will also appear the in the same format to any testers running a Usability Test for this project.
In Botmock, you may come to a situation where you will want to use your variables in order to actually create a certain type of a response from whichever API that you call using the API Block. To set this up, we will be using the JSONPlaceholder API again, but this time, setting up a POST request to properly demo this.
First, you will select POST as your request type and Request URL as "https://jsonplaceholder.typicode.com/posts".
For your Request Parameters, you will have the Key be: title. Then, your value is where you can actually pass the variable, so in this example, it will be: I like %ProductSelected% . Initially, without any variable passed yet, this is what the API response will look like:
When it all comes around and you test using a real variable, the Title will be pulled out and the variable that was entered in the test will be passed through that sentence.
Finally, for Response Mapping, you will have the Response JSON Path as "title", and then map it back to the variable "PostTitle". Now in this use case, we are essentially generating a new "Title" for a blog post that we are creating using this process.
With all of this together in the API Block, it should look like this:
And there you have it! You have now setup and hopefully, successfully utilized the API Content Block. From here, the choice is yours on how to be able to GET and POST Data within your prototypes, but with this feature, the possibilities are now nearly endless with the ability to easily bring external data into the Botmock platform and use it for more clear and accurate prototypes.
If you run into any questions about API Block, simply start a conversation on our live chat or send an email to help@botmock.com. Happy Building!