API

Learn all things APIs in BotWiz!

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.

What is an API?

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.

Request Methods

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.

Common Request Methods

GET

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

POST

POST is used to send data to a server to create/update a resource. Most commonly used to 'post/send' data to a server, rather than update.

The data sent to the server with POST is stored in the request body of the HTTP request:

Request Body for a POST request in BotWiz

As you can tell from the start, the request body works by sending key/value pairs in the request. Think of this as JSON keys and entries. As that is exactly what it is, BotWiz just removes the need to use {} or "" in the request. Taking something from this:

{
   "key": "value"
}

And turning it into:

Key: key Value: value

Some notes on POST requests:

• POST requests are never cached

• POST requests have no restrictions on data length

• POST requests transmit data via the request body object.

• POST requests can still send values via query params (In the URL)

PUT

PUT is used to send data to a server to create/update a resource.

The difference between POST and PUT is that PUT requests are idempotent. That is, calling the same PUT request multiple times will always produce the same result. In contrast, calling a POST request repeatedly have side effects of creating the same resource multiple times.

DELETE

The DELETE method deletes the specified resource. This wont be as commonly used in BotWiz as typically it is only used if you control the data server for the resource you are sending the request to.

PATCH

The PATCH method is used to apply partial modifications to a resource. This is commonly used in Discord endpoints in which you update a resource. Such as message, channel or guild, etc.

Not So Common Request Methods (Not used in BotWiz)

HEAD

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.

OPTIONS

The OPTIONS method describes the communication options for the target resource.

CONNECT

The CONNECT method is used to start a two-way communications (almost like a tunnel) with the requested resource. This is different from a websocket.

TRACE

The TRACE method is used to perform a message loop-back test that tests the path for the target resource (useful for debugging purposes).

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.

API block in BotWiz

Sending HTTP Requests

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.

API block configuration menu

Setup Tab

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.

URL Parameters

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.

URL Parameters Tab

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

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.

HTTP Headers Tab

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.

Request Body

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.

Request Body

Test Request

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.

Retrieving Response Data

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:

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

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:

Normal Object Response

{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

Response Object With Arrays

{
    "data": {
      "users": [
        {
          "firstName": "Bryan",
          "countryCode": "PW",
          "country": {
            "name": "Palau"
          },
          "company": {
            "name": "Mastercard"
          }
        },
        {
          "firstName": "Bryan",
          "countryCode": "CG",
          "country": {
            "name": "Congo (the)"
          },
          "company": {
            "name": "China Construction Bank"
          }
        },
        {
          "firstName": "Bryan",
          "countryCode": "BV",
          "country": {
            "name": "Bouvet Island"
          },
          "company": {
            "name": "Chevron"
          }
        }
      ],
      "countries": [
        {
          "iso3": "RUS"
        }
      ]
    }
  }

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.