API
Learn all things APIs in BotWiz!
Last updated
Learn all things APIs in BotWiz!
Last updated
The API block allows you to send restful HTTP requests to 3rd party servers to append, delete or retrieve information from the server side. APIs are super handy when you need to communicate with an outside service that is not natively integrated with BotWiz. Sending HTTP requests with BotWiz is super simple. Below is a general outline on how to use this block and send successful requests. Given APIs can be complex, this guide will be elongated to cover as much as possible to make it as easy as possible to understand.
Before sending requests to servers, it is relatively important to understand how a HTTP request works. For those who know what a HTTP request is and how it works, click here to skip this section.
The Hypertext Transfer Protocol (HTTP) is designed to enable communications between clients and servers. HTTP works as a request-response protocol between a client and server.
Example: A client (browser) sends an HTTP request to the server; then the server returns a response to the client. The response contains status information about the request and may also contain the requested content.
Simple enough right? Well, each HTTP request must be sent with a designated 'method'. Each method does different things and means different things. Annoying right? Yes, we know. A list of each request type/method can be found below.
GET is used to request data from a specified resource. This method cannot accept any bodies on the request. As such all query parameters must be sent in the URL. Like the example below:
/test/demo_form?name1=value1&name2=value2
Some notes on GET requests:
GET requests can be cached
GET requests have length restrictions
GET requests are only used to request data (not modify)
GET requests cannot pass any data via the request body
HEAD is almost identical to GET, but without the response body.
In other words, if GET /users returns a list of users, then HEAD /users will make the same request but will not return the list of users.
A HEAD request is useful for checking what a GET request will return before actually making a GET request - a HEAD request can read the Content-Length header to check the size of the file, without actually downloading the file.
Now you know all the types, you can start to use HTTP requests more confidently. You can get started using the API block in BotWiz to send requests to servers.
To get started sending HTTP requests with BotWiz, you first need to add the API block to your command/event tree, the block is pictured above for reference. Once you have added the API block to your command/event tree, you can configure the request by clicking on the block itself to open the configuration menu.
Once open, you will be greeted by a couple different options, if this is your first time using HTTP requests, this may seem confusing at first glance. However, it is super simple to setup and use. On the first page 'Setup' which is open by default you will be greeted by 3 input boxes.
Name The name of the API block, used to reference the response with {api_api_name_here[response]}
URL The URL/Address for the resource you are sending a request to
Method The method/type of request it will be
When picking a name for your API block, it is best to keep it simple, and note that it MUST be unique, you cannot have 2 or more API blocks in the same command/event with the same name, or this will confuse the responses and may lead to issues down the line.
The second page/tab you will see is the URL Parameters tab. This is used to add query params to your URL, used mainly for GET requests, but widely used across all methods which accept URL params.
The URL parameters are accepted in Key/Value form to keep it simple. To shorten it all down and keep it as simple as possible, essentially this will append the key and value to the end of the URL when sending the request. It could end up looking something like this:
/test/demo_form?name1=value1&name2=value2
HTTP Headers are used to pass important data to the servers you are sending a request to, data such as: Authentication tokens, request data type, and other bits of information the server may need to respond and process your request correctly.
This is most commonly used for stating the data type, and authenticating the request when using endpoints which require keys or tokens.
Never share any authentication key with anyone. Make sure to keep this secret at all times! BotWiz allows you to use {bot_token} to send your bots token in an API request without the need to copy and paste it. Only use this variable in Discord APIs, other APIs do not need it.
As you can see, this also works in a Key/Value pair. Exactly the same as the URL Parameters. This is also the same for Request Body, which is the next section we will cover.
The request body is usable on all request methods besides HEAD, and GET. The request body allows you to send data to the server, This data is sent as JSON and parsed on the receiving end. If you need to send data with your request, it will most likely be a POST or PUT request that uses the request body to send such data.
The test request tab is used to send a request to the server from the builder so you can see the response of the request. This is useful for testing the request, or viewing the data it will return so you can correctly reference it in your event or command.
Test requests send like a normal request, the only difference is it is sent by the builder and not the bot.
The use of any variables aside from {bot_token} will not work in a test request.
Once you have sent a successful request, you can use it's response in your commands or events. Note the requested data is specific to that interaction, meaning once the command or event finishes its trigger, the request data is deleted to make room for the next run.
Request data cannot be transferred from one command, to another. Or one event, to another, unless you save the response from the HTTP call to a custom variable, however unless needed, it is advised you do not do this as storing data will mean it does not get updated without you specifically making it.
To display the data from the request you can use the API response variable, this looks like:
{api_your_api_name[response]}
Remember to replace 'your_api_name' with the name you have chosen for the API block when setting it up. After response you will use dot '.' notations to add another argument to the variable lick such:
{api_your_api_name[response.example]}
The above is an example of me retrieving the value stored in the 'example' key of the JSON response the server sends back. Everything that comes after response should match with what is returned in the response from the server the request was sent to. For example, I have sent a request and received this response:
I want to access the title of this response, to do this i would write out the variable as such:
{api_your api name[response.title]}
This will retrieve the data from title and return "delectus aut autem". When working with responses that return an array of objects, it is slightly different. Here is an example:
As you can see, there are some responses that have been returned as an array with objects inside them (Objects use {} and arrays use []}. This is all in JSON format. Learn more about it here.
To access a value in an array, we must specify the arrays name, and the position of the object/data value in which we want. It is important to explain now that arrays ALWAYS start at 0. Now that we know this, lets say I want to access the second user in the users array (Bryan) and then retrieve the name of his country. This is how I would do it.
{api_your api name[response.data.users.1.country.name]}
As you can see, I have defined the index/position number for the user object I want to access. This is important when working with arrays, or the bot will not know which one to return, and instead will return null, the variable or even [Object object].
Lets say I want to get the only object in the countries array. This is how I would do it:
{api_your api name[response.data.countries.0.iso3]}
This will return 'RUS' as the value.
