This tutorial is the third and final part of a series exploring 3d Printing APIs. In the previous two tutorials we learned how to obtain read and write access to the Thingiverse API. Now we will build a small command line based app using what we’ve learned. It is necessary to have completed part 1 of this series before moving onto this section. Also please note: this tutorial is for Mac OS systems. It may be possible to provide a PC version later if there is enough demand for it.
Problem Statement
The problem that our sample app will attempt to solve is the current inability to load more than 12 images at a time when browsing the Thingiverse website. Visit https://www.thingiverse.com/explore/featured and notice how it only shows 12 images of featured designs at a time, and it takes a second to load the next 12 and so on. This is too slow. We want instant Thingiverse gratification- so we will build an app that loads the first 300 featured images. To keep things simple, this app will not be an external website, but will be a small app that runs on your own personal computer.
Working With What We Have
Often when using an API, we are limited by what the API provides. Let’s take a look at the “featured” function and see if it gives us the information that we need to make our app.
1. In your browser visit the following URL using your App Token from the first tutorial. Remember that the App Token is for read-only access, whereas the Access Token from the second tutorial is for both reading and writing. We only need to read information so we’ll use the App Token. If your App Token is 123456 visit:
https://api.thingiverse.com/featured?access_token=123456
Notice that there are 30 things returned.
2. Let’s view the next “page” of 30 things by adding “page=2” to our URL. Visit:
https://api.thingiverse.com/featured?access_token=123456&page=2
Thingiverse provides up to about 150 pages of featured things. So if we want the first 300 items, then we’ll need pages 1 through 10.
Now we need to see if we can get images from this API response. Click on a thumbnail link and it will show you the thumbnail image of the thing. Great!
Now we know that the API is capable of giving us the first 300 featured images, and we can build an app to display them.
The Command Line
The command line is an important tool that comes with your computer’s operating system. It is a way to manually operate any task on your computer without using it’s graphical interface. You can make many powerful commands with it such as creating, editing, deleting files and making http requests. On Mac OS systems it is called the “Terminal”. “Terminal” and “command line” are terms that are often used interchangeably. Let’s get familiar with it.
1. Open the command line by going to Applications > Utilities > Terminal
2. Go to your home directory by entering “cd”.
List all of your folders in your home directory by entering “ls”.
You should see a list of your folders.
As a reality check open up your file finder and see that the folders are indeed the same.
3. Let’s make a practice folder where we will place our app.
Enter “mkdir practice”.
This created a new folder.
You can type “ls” again and you will see our new practice folder listed.
Go into the practice folder by entering “cd practice”.
4. If you ever feel unsure of what folder you are in, you can always go back into your practice folder by entering “cd” then “cd practice”.
cURL
cURL is a useful tool for making http requests from the command line, and is how we will make our API requests. Let’s experiment with it.
On your command line enter the same URL that we visited before before, preceded by the curl command. Be sure to add quotes around the URL.
curl "https://api.thingiverse.com/featured?access_token=123456"
You’ll see the JSON returned to you in the command line.
Now get the second page, remembering to add the quotes:
curl "https://api.thingiverse.com/featured?access_token=123456&page=2"
Now that we have a way to bring in JSON information from the API to the command line, our app will need to do the following tasks to process that information:
1. Make ten cURL requests to get the first ten pages of featured items.
2. Filter through the JSON response to get the thumbnail links.
3. Save the links into a file.
4. Add an html tag to each link in the file to make them viewable as images.
Fortunately there are some useful command line tools that can help us.
Installing the Tools
We’ll need three tools: homebrew, gawk and jq.
1. Homebrew is a tool manager that makes sure that the correct tool version for your particular system is installed and that anything that it depends on is installed too.
Install homebrew from here: https://brew.sh/.
It will tell you all you have to do to install it, is paste a line of text in your terminal. If you’re new to working with the command line and feel that you don’t fully understand what’s going on- that’s natural. Usually the best thing to do is take a deep breath and follow the instructions. It may take a few minutes for homebrew to install.
Test that you have successfully installed it by running “man brew”.
It will show you the operating manual.
Exit out by typing “q”.
2. Gawk is a file parsing tool that will help us convert our file of thumbnail links into html images. Have homebrew install it by entering “brew install gawk” on your command line. Everyone’s operating system is different and you may get various prompts from your computer. For example mine asked me to agree to the xcode license agreement before installing. As mentioned before, often the best thing to do is just follow the instructions. So I entered the command that it gave me and my password when prompted.
Test that you have successfully installed it by running “man gawk”. As always, you can exit out of manuals by typing “q”.
3. JQ is a JSON parsing tool that will help us extract the thumbnail links from the API response. Download it by running “brew install jq”. Check with “man jq”.
Running the Code
Hopefully you were able to install the tools- which was the most difficult part of this tutorial. Now comes the fun part where we get to run the code!
1. Cd into your practice folder. Incorporating the same curl command from before (and making sure to use your real App Token instead of 123456) enter the following command. Note: you will need to scroll to the right to get the entire command.
for i in {1..10}; do curl "https://api.thingiverse.com/featured?access_token=123456&page=$i" | jq '.[] | .thumbnail'; done >> thumbnails.html
You will see the ten cURL requests being sent.
2. Check that it created the thumbnails.html file by entering “ls”.
Open the file by entering “open thumbnails.html”.
You’ll see the thumbnail links text open up in a browser window.
Let’s break down the components of the command and explain how it worked.
for i in {1..10};
This means for each number in the range of 1 through 10 perform the following task.
do curl "https://api.thingiverse.com/featured?access_token=123456&page=$i"
This defines the task as our cURL command.
| jq '.[] | .thumbnail';
This tells jq to extract the thumbnail link from the JSON.
done >> thumbnails.html
And finally, this says once it’s done save the results into a file called thumbnails.html.
3. Now we’ll use gawk to convert each link in the file into an html image tag so it will show up as an image when we open it. Enter the following (remembering to scroll to the right):
gawk '$0="<img src="$0" width=15%>"' thumbnails.html > thumbnails_temp.html && mv thumbnails_temp.html thumbnails.html
Now open the file again with “open thumbnails.html”. You’ll see all 300 images in the browser. Yay!
Breaking this command down we have:
gawk '$0="<img src="$0" width=15%>"' thumbnails.html
This tells gawk to surround each link in thumbnails.html with an html image tag making the image visible in the browser. And it specifies the image width to be 15% of the computer screen.
> thumbnails_temp.html && mv thumbnails_temp.html thumbnails.html
This is an intermediate step which saves the changes to a temporary file “thumbnails_temp.html” and then replaces the contents of the old file with it.
Congratulations! You have made your own app using the Thingiverse API! Although this was not deployed to an external web page, it encapsulates some of the main inner functions of web apps that use APIs. These functions include: getting authorization from the API, making requests to the API, parsing the JSON response, and displaying the formatted information on an html page.
