How To Use the Thingiverse API: Basic Read Access

This tutorial is part 1 in a series exploring 3d Printing APIs.  Anyone can follow these steps to get basic read access to the Thingiverse API- no previous software experience is required here.  

Have you ever wanted to create your own 3d Printing mobile app or website?  Say for example that you wished that Thingiverse had more advanced search options to filter and sort through it’s myriad designs.  Wouldn’t it be nice if you could get that information from Thingiverse and use it to power your own custom website?  Or say that you wanted a website that allowed you to easily tweet a design that you like on Thingiverse with the press of a button.  Fortunately there are quite a few 3d Printing websites that encourage you to develop creative applications using their information.  They enable this by providing what is called an API.

API stands for Application Program Interface, and it is a standardized way for two applications (such as the Thingiverse website and your super awesome custom website) to share information with each other.

Thingiverse offers a public API that requires no special permission to access- other than having an account.  Other sites like Youmagine, Yeggi, MyMiniFactory, and Cults 3d offer API’s which you can access once they have approved your website/app idea. 

This tutorial will show you how to quickly get started with accessing basic information from the Thingiverse API.

Getting your Access Keys

  1. If you haven’t already, sign up for a Thingiverse account at:  https://accounts.thingiverse.com/register
  2. Log into Thingiverse and go to https://www.thingiverse.com/apps/create
  3. Under “Select A Platform” select “Web App”. 
  4. Enter the name for your App and a description of it.  Note: if the name is already taken it will prompt you to choose another.  Thingiverse doesn’t really read this information- you can type gibberish and it will still work.
  5. Click the “I agree to MakerBot API terms” checkbox.
  6. On the top right of the page click “Create & Get App Key”.
  7. You will be taken to a page that allows you to enter optional information about your application, but you can leave these blank.  The important things on this page are the “Client ID”, “Client Secret”, and “App Token”.  Copy these three things and save them securely somewhere.  These are your identification keys that give you access to the API.  On the top right of the page, click “Save App”.

You now have everything need for “read only access” to the Thingiverse API!

Accessing Information

  1. Let’s begin with accessing some basic information like a list of all the popular items in Thingiverse.  Open up a browser window and enter:
    https://api.thingiverse.com/popular?access_token=

    Plus add your App Token that you saved from the previous steps to the end.  So if your App token was 123456, it should look like:

    https://api.thingiverse.com/popular?access_token=123456

    This is called a URL and is composed of a domain name (api.thingiverse.com), a path (/popular), and a query parameter which in this case is our access token (?access_token=123456).
    url

  2. You will get what looks like a bunch of gibberish.  This is called JSON (Javascript Object Notation) and is the language which APIs use to talk with each other.  Contained in the JSON is all the information that you requested.  Look closely and you’ll see names and ids of popular designs on Thingiverse.

    ugly

  3. If you’d like to make the JSON easier to read and are using Chrome, add the JSONView chrome extension https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en.  Once you’ve added the extension, open another Chrome tab and re-enter the url from step 1.  You’ll see the information in a much more readable format.

    pretty
  4. Looking at the information, we can see things like: id, name, url, public_url, thumbnail, creator, and links associated with each.  Just for kicks, click on a link for a thumbnail.  It will show you the image of the item!

Digging Deeper

As I mentioned before, this tutorial covers obtaining “read access”, but it does not cover obtaining “write access”.  What is the difference between the two?  Read refers to “getting” information as we did above.  Write refers to “setting” information such as creating, editing, or deleting things.  We’re going to look at Thingiverse’s API documentation to see what kinds of information we can get with our read access.

Thingiverse has good documentation about their API which you can view here https://www.thingiverse.com/developers/rest-api-reference.  This gives you instructions on how to use the API to perform all of it’s read and write functions.  Click on the “Things” menu option on the right and you’ll see “GET /things/{$id}/”.

documentation

You can tell that this function is for reading (“getting” information) because it is prefixed by “GET”, and therefore is available to us.  This particular function allows us to get the information on a particular “thing” or design by adding the path “/things/<id of thing>” to the end of our domain name, followed by our app token- using the same URL pattern as before.  Always add your app token at the end of your requests or you will get an unauthorized error.  Let’s try this function out.

  1. Go back to our first URL:
    https://api.thingiverse.com/popular?access_token=123456

    Pick an id from one of the things.  We’ll use id 2238443 as an example in step 2 but you can use the id you picked.

  2. Now visit:
    https://api.thingiverse.com/things/2238443?access_token=123456

    You’ll get all the information that Thingiverse has on that particular thing such as files, description, creator, photo links, etc.

show

Feel free to play around with the “GET” functions in the documentation.

Keeping track of your Apps

If you ever need to look up your access keys again or if you want to edit your app details:

  1. Sign in and go to your profile on Thingiverse.
  2. Click on Apps from the menu near the top right of the page.
  3. Click on your App, and click the “Edit” button.

I hope that this helped demystify APIs a little and showed that you can interact with them using just your browser.  The second part of this series will cover how to obtain write access.  

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: