This tutorial is part 2 in a series exploring 3d Printing APIs. The previous tutorial covered how to get basic read access. Now we will cover obtaining write access. It is necessary to have completed part 1 before moving onto this section, as it builds on previous work.
We saw in part 1 how we can use a read-only App Token to get information from Thingiverse. Now we will get a special Access Token that will allow us to actually change information on Thingiverse such as create, and delete things. This is a very powerful privilege that enables you to do things such as “like” hundreds of designs in less than a minute, or “unlike” them just as fast. You can edit and delete files, and even change a user’s profile information. However with great power comes great responsibility and Thingiverse uses something called OAuth to ensure that write access is safely granted to third party apps such as yours.
OAuth (Open Authorization) is the standard for third party app authorization on the internet. In our case it involves three players: your app, the Thingiverse API, and a user that has an account on Thingiverse. The goal of OAuth is to allow the user to safely grant your app access to their Thingiverse account, so that it can read and write information on Thingiverse- on their behalf. For example, once the user grants permission, your app could have that user’s account like or dislike things, make comments, add or delete designs, and even change their profile information.
The Thingiverse OAuth is summarized as follows:
1. The user logs into their Thingiverse Account- the browser will automatically save their access credentials.
2. You send a request to Thingiverse with your app’s ID and the user’s access credentials (that the browser saved). This request asks Thingiverse permission to access the Thingiverse API on behalf of the user.
3. Thingiverse asks the user if it’s OK for your app to do so.
4. User agrees.
5. Thingiverse sends you a secret access token. Whenever you make an API request, you have to send that token with it. The token gives your app authority to make changes to Thingiverse on behalf of the user’s account.
Getting your Access Token
In order to make things as simple and safe as possible, the “user” in this tutorial will be you. So your app will be accessing Thingiverse on behalf of your account. Also please note that in all of the screenshots I have changed my access tokens to invalid ones, for obvious reasons.
1. Login to Thingiverse. This will automatically save your access credentials to your browser.
2. Remember from the first tutorial when you saved your “Client ID”, “Client Secret”, and “App Token”? Visit the following URL in your browser, using your Client ID. For example if your Client ID is 123456, it should be the following. Note: you may have to scroll to the right to see the entire URL.
https://www.thingiverse.com/login/oauth/authorize?client_id=123456&response_type=token
This request asks Thingiverse permission for your app (identified through “client_id=123456”) to access your account (identified by the access credentials saved in your browser when you logged in) and that you want it to respond with an access token (“response_type=token”).
3. Thingiverse will ask if you agree to grant your app permission to access your account. Click agree.
4. When you registered your app, we skipped over entering some details. One of those details was the URL for your app. Thingiverse will try to redirect back to this URL, but since we didn’t enter one, you’ll get an error page. That’s OK. Look at the browser’s address bar. It’s the same URL that we entered, but Thingiverse added the secret access token to the end. Yay!
5. Copy your access token (everything after “#access_token=“). Save this access token safely somewhere. Note: the access token will likely be too long to show fully on your browser address bar. Make sure to use your cursor and right arrow key to manually move all the way to the end of the URL to copy the entire token.
6. Test your access token out by visiting the URL for popular items from the first tutorial. So if your access token is 123456, then you would visit:
https://api.thingiverse.com/popular?access_token=123456
If you see the JSON response listing the popular items, you now have everything need for write access to the Thingiverse API.
7. Save the id and name from one of the things, to use in the next exercise.
Creating Things
Let’s look again at the Thingiverse API Documentation to see what kinds of things we can create, viewable here: https://www.thingiverse.com/developers/rest-api-reference. Scroll about 1/3 of the way down and you’ll see “Like a thing: POST /things/{$id}/likes”.
In the first tutorial we discussed how functions with a GET in front are for reading information. The GET is called an http verb, and there are four other kinds of verbs: POST, PATCH, PUT, and DELETE. POST is for creating things, PATCH and PUT are for updating things, and DELETE is for deleting things. Therefore since our function has POST in front it means it’s a function for creating something. In this case, “liking” a thing is creating something because we’re creating a new “like”.
This function here is saying that you can “like” a thing by sending a POST request to a URL composed of the domain (https://api.thingiverse.com) + the path (/things/{$id}/likes) + the access token (?access_token={$access_token}). So for example if the id of the thing you want to “like” is 123, and your access token is 123456, your request URL will look like:
https://api.thingiverse.com/things/123/likes?access_token=123456
Let’s try it out.
1. In order to send a POST request we need a tool called Postman. Download it from here: https://www.getpostman.com/
2. Before we add a like to something, let’s make sure that you haven’t already liked it on your account. In another browser tab go to the Thingiverse website and under your account select “Things I’ve Liked”.
You’ll see photos of all the things you’ve liked (in my example there are none). Check that you haven’t already liked the thing that you picked in the previous exercise. If you have then pick something else.
3. Open up Postman and enter the POST URL we composed above.
Select POST.
Press Send.
4. Now refresh your “Things I’ve Liked” page and you’ll see it added.
Deleting Things
Going back to the documentation page you’ll see the function to unlike a thing as DELETE “/things/{$id}/likes”.
This means if you send a DELETE request to the same URL you will unlike the thing.
1. Going back to Postman, the previous POST URL should still be there. If it’s not, then re-enter it or click on a copy of it in the history log on the left.
Select DELETE.
Press Send.
Refresh the “Things I’ve Liked” page and it won’t be there anymore.
Congratulations! You’ve leaned how to get write access through Thingiverse OAuth and to successfully create and delete things.
Deleting your App
If you ever feel that your token’s safety has been compromised, you can always delete your test app.
1. Go to your Thingiverse profile.
2. Click on Apps from the menu near the top of the page.
3. Click on the app, and click the “Edit” button.
4. Scroll to the bottom and you’ll see a button “Delete App”.
In the next and final part of this series we will create a small command line app using what we’ve learned.
