A beginner's guide to the TeachBoost API
This guide is designed for beginners with little or no experience interacting with and using APIs. At the end you should have both your computer set up and the knowledge to run your own API queries and get your TeachBoost data programmatically!
What is an “API”?
API stands for "application programming interface." The TeachBoost API is designed to be used over the internet and provides a particular set of tools and definitions for you to interact with your data stored in TeachBoost.
Normally when you use TeachBoost, you view and interact with your data using a web browser like Safari, Chrome, or Firefox. You click links or enter a URL in the address bar, and the browser shows it to you in the way we present it.
With our API, however, you don't use a web browser; instead, you view and access your data using "commands" that you type. It's a little bit different but once you learn the basics it's not difficult or scary! While you can type these commands in any number of tools, we're going to focus on just one of them in this guide: the command line interface, or "CLI," or "terminal."
The other help docs in our API section all explain the different types of data and the commands you need to access them.
Using the “Command Line Interface”
The command line interface (we're going to call this "CLI" from here on out) is a tool on your computer that lets you type commands into it. You can interact with your computer or websites this way and it provides a useful and much faster method for computer programmers and IT staff.
It might seem daunting at first because it's all text, but once you use it and realize that the CLI just receives specific commands you enter and returns the results it's a lot less scary.
Opening the CLI
On MacOS
If you're using a Mac computer, the CLI is an app called "Terminal" and it already comes with everything you need. To open it, look for the app called Terminal in your /Applications folder or in Launchpad and then double click it. You can also click the search icon at the very top right (in the "menu bar") and then search for "Terminal", then click Enter.
Once you have Terminal open, it will look something like this:
On Windows
If you're using a Windows computer, you'll need to install a separate app called Cygwin that comes with all of the tools you need. Windows' CLI doesn't have the basic features that the TeachBoost API and other APIs need, so we need to install a different one.
Please follow these steps on Oracle's website to install Cygwin, they're extremely clear and walk you through everything you need.
Once you've successfully installed Cygwin and opened it, it will look something like this:
Using the CLI
Now that you have the CLI open on your particular system you're ready to start typing commands! We're just going to type a few things in to get a feel for it now, and then later we'll start interacting with the TeachBoost API to download our first set of data.
Whenever we show a command here in this guide, we start them with this symbol: $>. This indicates a new command that is all on one line. Don't press enter until we say to press enter, even if a command in this guide wraps to a second line! You only press enter at the end of the line that starts with $>.
First, enter this command and after you've typed it all, press Enter:
$> pwd
This command is short for "print working directory" and will show you the file directory that you're currently within. By default, this should be something like /Users/Andrew on MacOS or C:/Users/Andrew on Windows. Take note of what directory the CLI tells you.
Now, let's run a different command to "change the directory", or cd. If you're using MacOS, type this:
$> cd ~
If you're using Windows, type the following (but replace "Andrew" with whatever your user name is on Windows):
$> cd C:/Users/Andrew
This will change the file directory to be your user folder. The CLI should now tell you that you're in that folder right above where you type.
Now, let's move into our "Desktop" folder by typing cd Desktop. You should now be "in" your Desktop folder on the CLI, meaning that any files you create will automatically be saved to that Desktop folder.
Now to put it all together!
Now that you have your computer system ready and some very basic CLI commands under your belt, you're ready to use the CLI to get your data out of the TeachBoost API!
Step 1: Get your TeachBoost API Token
The first thing you need before you start using the TeachBoost API is your custom API "token". This token is like a password that's unique to you and should always be kept private. You use this token every time you request data through the API so that we can verify it's really you making the request.
To get it, go to your Reports page on TeachBoost by clicking the "Reports" button on the left. Then click the black button at the top that says "Data API." This page is the API overview page and contains things like your token, a link to the help docs, and an "explorer" where you can get sample data back. Copy your token at the top right.
Step 2: Request a set of data
Now we're ready to roll! As an example, we're going to get score data from the API. First, take a look at the Scores API help doc to get some general information on this type of data and how you get it.
The first highlighted part at the top contains the URL you need to get this data. Here, it's https://teachboost.com/api/v1/scores.
Open up your CLI app and enter the following command in it to get your score data (we'll explain what this means after). Make sure to replace YOUR_API_TOKEN with the token you copied earlier!
$> curl https://teachboost.com/api/v1/scores --data "token=YOUR_API_TOKEN"
Click enter after typing that into the CLI and you should see all of your score data printed to the CLI in a weird format. Congrats! Now let's go over what we just did:
-
curl: this is the command to run the "cURL" program. cURL is software designed to download data from somewhere over the internet. In this case, we're downloading your score data from TeachBoost. -
https://teachboost.com/api/v1/scores: this is the URL, or "endpoint," you're telling cURL to download the data from. Our help docs contain all of the specific URLs you need depending on the type of data you're downloading. -
--data: this is a "flag" that tells cURL "send the stuff I type after it to the URL, and call it 'data'." You can tell it's a flag because it starts with two dashes,--. -
"token=YOUR_API_TOKEN": finally, the text within quotes is everything we're sending with the "data" flag. Here, we're sending the "token" that we set equal to your specific API token. We need to do this so that TeachBoost knows it's you asking for this data.
After you run this, you'll see all of your data within the CLI window. This is ok for small amounts of data, but if you get a lot back it can be unruly. Let's look at how we can download this to a file instead.
Step 3: Download your data to a file
To make things easier to work with, we're going to download this score data to a file on your Desktop. Use the commands above to make sure you're in your Desktop folder in the CLI (e.g., cd ~/Desktop).
Now, we're going to add another "flag" to our curl command to tell it "put all that data you just downloaded into a file instead of printing it to the screen":
$> curl https://teachboost.com/api/v1/scores --data "token=YOUR_API_TOKEN" --output "scores.txt"
Here, we added a flag called "output" and we told it to download all of the score data to a new file we're creating called scores.txt.
Note: if you're having trouble finding this file on your Desktop, you may not be in your Desktop folder in the CLI. You can use the following command (depending on whether you're using MacOS or Windows) to manually set the location, or "file path," to where you're creating this file:
MacOS:
$> curl https://teachboost.com/api/v1/scores --data "token=YOUR_API_TOKEN" --output "~/Desktop/scores.txt"
Windows:
$> curl https://teachboost.com/api/v1/scores --data "token=YOUR_API_TOKEN" --output "C:||Users||Andrew||Desktop||scores.txt"
Remember to change "Andrew" to your own computer's name.
Success! You just downloaded all of your score data to a file called scores.txt on your Desktop. If you double click this file it should open up in a text editor like Notepad, TextEdit, or perhaps even Microsoft Word.
Step 4: View your data
The data that you download from the TeachBoost API is saved in a format called "JSON," or "JavaScript Object Notation." This is an extremely popular data format for APIs and other ways of transmitting data over the internet, but you may not have seen it before and you may not know what to do with it now!
Now is a good time to loop in your IT department, Data Analysts, or someone who has programming knowledge in converting this data into something useful or usable for you. If you have experience programming in Excel, there are also ways of converting JSON-formatted data into an Excel spreadsheet in Visual Basic.
If you're looking to do this yourself and don't have programming knowledge, there are tools that convert JSON to CSV files but we cannot vouch for their security and do not recommend using them. If you'd like to try them with non-confidential data, Google shows a few options:
- Convert JSON to an Excel file: http://www.json-xls.com/json2xls
- Convert JSON to a CSV file: https://konklone.io/json/
We just want to remind you again that you should never share your API token with anyone—it's yours and it should be private. You should also never share your TeachBoost data with anyone outside of your organization unless you have explicit permission.
What's next?
We hope this beginner's guide provided enough information to both get you started and whet your appetite for learning more on APIs. When you're ready, you should take a look at our API docs to learn the other "endpoints" we have and how to access them.
Good luck!