Tutorials →

JavaScript Beginner Tutorial

Welcome to Zoo. We are building tools to be the backbone infrastructure for hardware tools.

Welcome to our JavaScript beginner tutorial. This is primarily for those that have little coding experience, have no idea what an API is, or have no idea how to use them.

What is an API?

API stands for Application Programming Interface. The key to an API is that it allows applications to talk and be used by one another. Here are some current examples of API's used today.

Uber drivers use Google Maps for navigation in the Uber app.
Duolingo allows users to log in using their Facebook information.
Shopify uses Stripe to process credit card payments.

API's are powerful. Let's take the Uber example above. It would take a lot of time and engineers to develop a map feature similar to Google Maps within the Uber app. Uber uses Google Maps' API to access it within their own app. Of course, Uber pays a portion of their sales to Google in return for using their API.

Let's Get Started

For you to communicate with Zoo's website, you must have an API key. When you make an API command, you will pass this API key along with your command, so that we can verify it's you.

You will see your API token below if you are signed in and have already generated one. If all you see is "Generate your first API token," then you currently do not have a token. Follow the steps below to generate an API key:

Create an account. If you haven't already, you can create an account here
Sign in. Once you've signed up for an account, make sure you are signed in.
Generate an API key. You can either go into your account settings to generate an API key, or you can press the button below and we will take care of it for you!

🚨🚨🚨 Please take a moment to sign up. 🚨🚨🚨

It's required in order to generate an API key and follow this tutorial.

Executing From Your Computer

First, we want to make sure you have the right tools to make your first API command from your computer. We will provide you with almost everything you need. There are a few files that you will need to download from the Zoo repository:

Download Here

The link will have you download a zip file. Place this zip file in an easy-to-access location on your computer (the Desktop is a simple spot). The .zip file contains plenty of files. However, only two of the files are needed for this example: a 3D model of a gear (gear.obj) and a Javascript file (convert.js).

Jump to the appropriate tutorial for your setup

Windows
Mac
Linux

Windows

Once you download the .zip file and place it somewhere you can easily access, extract the contents of your zip file. You can do this by right-clicking on the .zip file and selecting Extract Here. This will unpack the zip file and place all the contents into the current directory it's in.
Install the latest version of node.js for your machine here: Install Node.js
- make sure you download the correct version for Windows
Once you download node.js, you will need to open Powershell. One way to open the Powershell is to click on the Start button and type "powershell" and press enter
Once Powershell is open, you will need to install yarn. Yarn will allow us to install all the dependencies needed to execute this script. You can do this by typing the following command into Powershell and hitting enter:

npm install -g yarn

Now, navigate to the folder in which you put all the files. for example, let's say you put them on the Desktop, then you would type the following in Powershell and hit enter:

cd $HOME/Desktop/litterbox-main

cd stands for change directory. Once you hit return, you will be working inside the litterbox-main folder. For another example, let's say you put your folder you downloaded in a folder called ZooPractice within the Documents folder. This would look like so:

cd $HOME/Documents/ZooPractice/litterbox-main

Another method for changing directories is if you see the folder you want to move into (whether through File Explorer or the Desktop), you can type "cd" and then drag and drop the folder onto Powershell, it will automatically fill out the file path for you. Hit "enter".

You will now be working inside the folder you created called ZooPractice.

Once inside the correct folder, input the following commands into Powershell. This is going to install the dependencies needed to use the Zoo Typescript API. Make sure to replace "YOUR-API-TOKEN" with the token we mentioned earlier!

$env:ZOO_API_TOKEN="YOUR-API-TOKEN"
yarn install

Replace YOUR-API-TOKEN with one of your API tokens. It looks like you need to generate an API Token first.

This will install the necessary dependencies to run the Zoo Typescript API. Now, run the following command to execute the convert.js file:

node tutorials/beginner_tutorial/convert.js

As long as everything went smoothly, you will see the following output (Note: your STEP file will be called gear.step and be placed in the same directory):

File created successfully.

Curious how to write your own script? Click the button below for a step by step look into the convert.js file.

Code Rundown

Congrats! You just made your first successful API command using javascript. We offer plenty of API endpoints for you to use (file conversions, calculating center of mass, converting units, and more). Check them out here!

Mac

Once you download the .zip file and place it somewhere you can easily access, extract the contents of your zip file. You can do this by double-clicking on the file. This will unpack the zip file and place a new folder with all the contents into your directory.
Install the latest version of node.js for your machine here: Install Node.js
- make sure you download the correct version for Mac
Once you download Node.js, you will need to open your Terminal. You can open Terminal in a few ways:
- Press "cmd" + "space" and type in "Terminal" and hit "return"
- Press the magnifying glass icon on the top-right of your screen, type "Terminal" in the search box, and hit "return"
- Go to your Applications/Utilities folder. Double-click Terminal
Once Terminal is open, you will need to install yarn. Yarn will allow us to install all the dependencies needed to execute this script. You can do this by typing the following command into Terminal and hitting enter:

npm install -g yarn

Now, navigate to the folder in which you put all the files. As an example, let's say you put them on the Desktop. You would type the following in your Terminal and hit "return":

cd ~/Desktop/litterbox-main

cd ~/Documents/ZooPractice/litterbox-main

You will now be working inside the folder you created called ZooPractice.

Another method for changing directories is if you see the folder you want to move into (whether through Finder or the Desktop), you can type "cd" and then just drag and drop the folder onto Terminal, it will automatically fill out the file path for you. Just hit "return".

Once inside the correct folder, input the following command into Terminal. This is going to install the dependencies needed to use the Zoo Typescript API.

export ZOO_API_TOKEN="YOUR-API-TOKEN"
yarn install

Replace YOUR-API-TOKEN with one of your API tokens. It looks like you need to generate an API Token first.

This will install the necessary dependencies to run the Zoo Typescript API. Now, run the following command to execute the convert.js file (note: this may take 15 to 20 seconds due to the size and complexity of the gear.obj file):

node tutorials/beginner_tutorial/convert.js

As long as everything went smoothly, you will see the following output (Note: your STEP file will be called gear.step and be placed in the same directory):

File created successfully.

Curious how to write your own script? Click the button below for a step by step look into the convert.js file.

Code Rundown

Congrats! You just made your first successful API command using Javascript. We offer plenty of API endpoints for you to use (file conversions, calculating center of mass, converting units, and more). Check them out here!

Linux

Once you download the .zip file and place it somewhere you can easily access, extract the contents of your zip file. You can do this by right-clicking on the .zip file and selecting Extract Here. This will unpack the zip file and place all the contents into the current directory it's in.
Install the latest version of node.js for your machine here: Install Node.js
- make sure you download the correct version for your machine
Once you download node.js, you will need to open your Terminal. There are a few ways to open the Terminal:
- Press "CTRL" + "ALT" + "T"
- Click the Terminal icon amongst the list of all apps.
Once Terminal is open, you will need to install yarn. Yarn will allow us to install all the dependencies needed to execute this script. You can do this by typing the following command into Terminal and hitting enter:

npm install -g yarn

Now, navigate to the folder in which you put all the files. As an example, let's say you put them on the Desktop. You would type the following in your Terminal and hit "enter":

cd ~/Desktop

cd stands for change directory. Once you hit return, you will be working inside the litterbox-main folder. For another example, let's say you put your folder you downloaded in a folder called ZooPractice within the Documents folder. This would look like so:

cd ~/Documents/ZooPractice

Another method for changing directories is if you see the folder you want to move into, you can type "cd" and then just drag and drop the folder onto Terminal, it will automatically fill out the file path for you. Just hit "return".

You will now be working inside the folder you created called ZooPractice.

Once inside the correct folder, input the following command into Terminal. This is going to install the dependencies needed to use the Zoo Typescript API.

export ZOO_API_TOKEN="YOUR-API-TOKEN"
yarn install

Replace YOUR-API-TOKEN with one of your API tokens. It looks like you need to generate an API Token first.

node tutorials/beginner_tutorial/convert.js

As long as everything went smoothly, you will see the following output (Note: your STEP file will be called gear.step and be placed in the same directory):

File created successfully.

Curious how to write your own script? Look down below for a step by step look into the convert.js file.

Code Rundown

This is a quick look inside the convert.js file. Here we will go through the code line by line and explain what's happening, so you can create your own code! First, a look at the entire code:

import { file } from '@kittycad/lib/import'
import fsp from 'fs/promises'

async function convertOBJtoSTEP() {
    // Use KittyCAD client library to output base64 string from OBJ to STEP
    const response = await file.create_file_conversion({
        output_format: 'step',
        src_format: 'obj',
        body: await fsp.readFile('./gear.obj', 'base64'),
    })


    for (const key in response.outputs) {
        if (response.outputs.hasOwnProperty(key)) {
          const output = response.outputs[key];
          const outputFilePath = "./gear.step";

          console.log(`Saving output to ${outputFilePath}`);

          const decodedData = Buffer.from(output, "base64").toString("utf-8");
          fsp.writeFile(outputFilePath, decodedData);
        }
    }
}

convertOBJtoSTEP()

The first two lines are importing the Zoo (KittyCAD) library, as well as the fs/promises library.

import { file } from '@kittycad/lib'
import fsp from 'fs/promises'

The KittyCAD library is what we will use to do the OBJ to STEP file conversion.
The fs/promises library is what we are using to write a new file after we do the conversion.

The next segment in the code is responsible for the file conversion:

async function convertOBJtoSTEP() {
    // Use KittyCAD client library to output base64 string from OBJ to STEP
    const response = await file.create_file_conversion({
        output_format: 'step',
        src_format: 'obj',
        body: await fsp.readFile('./gear.obj', 'base64'),
    })

This is where the oo API command is. We create a new function called convertOBJtoSTEP(). In the function we store the returned value into a variable called "response". The file.create_file_conversion needs three parameters: The output_format (obj, step, stl, etc.), the src_format (obj, step, stl, etc.), and the body (the 3D model). The 3d model needs to be passed in as a base64 encoded string, so we use the fs/promises library to do this. We use await fsp.readFile('./gear.obj', 'base64'). This line will only work if the 3D model is in the current directory. If it's in a different directory, you will need to state where the 3D model is (for example, ./Desktop/ZooPractice/gear.obj)

The last segment of the code is responsible for writing the new file. Since the api call allows for multiple exports, we need to loop through the response.outputs object and write a new file for each one. In this case, we only have a single STEP export. We get the base64 data from reponse.outputs, decode it to a string, and write it to a new file.

for (const key in response.outputs) {
        if (response.outputs.hasOwnProperty(key)) {
          const output = response.outputs[key];
          const outputFilePath = "./gear.step";
        
          console.log(`Saving output to ${outputFilePath}`);
        
          const decodedData = Buffer.from(output, "base64").toString("utf-8");
          fsp.writeFile(outputFilePath, decodedData);
        }
    }

fsp.writeFile takes two parameters: the first one is what you would like the file to be named. In this case, we call it "gear.step". The second parameter is the information you want written in the new file. In this case, decodedData has all the information for the STEP file.

Found a typo?