Training

Local Web API Introduction for the Bestie I

A local Web API is the easiest way to get started with coding on your Bestie I. Indeed, it’s one of the easiest ways to start coding today in any form. Let’s walk through some basic ideas and examples. First, what is a local web API?

What is a Local Web API

An API is a way to interact with data. Data, in this case, is all the information stored on your Bestie I. So, the API contains things like your castles, rooms, items, grimoires, and more. Just like a home, to gain access, you have to open a door. That door is known as an endpoint.

A home full of data can have dozens of doors. Usually there’s a few main doors, like something to the front, back, garage, basement, and then more doors, like three bedroom doors, a bathroom door. Each one of those doors leads to some kind of data inside.

In a home, a door is made of wood, and usually shaped like a rectangle. For an API, the door is a bunch of code in your computer, and is shaped like internet address that starts with http:// or https://. So, for instance, the main API door for the Bestie I, the front door, is at http://{ip_address}/api/v1/

What’s that door address?

Notice that the door address above, the endpoint, starts with http://{ip_address}. What is that all about?

{ip_address} is actually the numbers assigned to your computer on the internet in your home. So, usually it’s something like 192.168.0.23 or 10.0.1.42. So, if you knew what that number is for your Bestie I, you would be able to type in http://192.168.0.23/api/v1/ in your web browser address, and you would be able to see some data! It will look something like this:

local web API view

The reason this is known as local is because the computer lives on your home network. If it existed somewhere out there in the cloud, it would not be local. This is not the time or place to discuss why one may be better than the other. For our purposes here, what you need to know is that to store your data, we chose to use your local network. That means your information never travels outside your home when it’s being recorded.

You can see in the image above a number of potential endpoints, or doors, to get information. So, to get the brain abilities information from the brain, you would put in http://{ip_address}/api/v1/brain-abilities/ If you did that right now though, you would get an error. That’s because we protect the doors of the house with locks, and we need a key. The problem is, you won’t be able to send the key to the door from your web browser. You need another tool.

Tools for Speaking to the Brain

To talk to the local web API on the Bestie I brain, you have multiple options. You can use the command line on your computer, or you can use a very popular tool called Postman. We plan on discussing these tools more in a later post, and the details will be in the developer tools.

It’s important to understand the language as well. We use something called JSON to send information back and forth. It looks something like this:

[
  {
    "id": 1,
    "name": "Speilburg Castle",
    "is_primary": true
  },
  {
     id": 2,
     "name": "Castle Daventry",
     "is_primary": false
  }
]

This is known as a collection, which is an object(s) in a list of items. Here, we have two items in our list, one with a name of “Speilburg Castle“, and the other of “Castle Daventry“. So, when we contact the endpoint http://{ip_address}/api/v1/castles/ with what’s known as a GET command, it returns the above to our program.

What do we do with this information? We’ll talk more about that in our next topic on How to Use Postman with Your Local Bestie I Web API.