Using the Instructables Unofficial API

instructaBUBBLES!

It's a web app that displays a bunch of recently published Instructables as an interactive bubble-chart.

You can try it out at https://instructabubbles.herokuapp.com/.

I decided to build this after discovering that Instructables.com has an unofficial API hosted by Mashape.com.

Now, if...

A) you know all about API's - click the link above and go check it! All you need to do is sign up for a Mashape account and you'll get your unique API key.

B) you're now quite sure what that means - read on for more explanation.

* note this an UNOFFICIAL API, meaning Instructables doesn't guarantee it won't change without notice, likely breaking any applications you build using it.

The unofficial Instructables API is a handful of URLs. Most people are familiar with URLs as the text you see and sometimes type in the bar at the top of a web browser. We can think of them as an address and message rolled into one for communicating with a web server. When a web server receives a request via a URL it responds by sending some specified set of information..

The three URL Endpoints (marked with a green arrow in the screenshot) provided by Instructables and their responses are...

• Get Categories - sends a list of Instructable Categories (Technology, Food, etc) with Channels (Audio, EL Wire, etc) nested inside
• Get List - sends a bunch of Instructables in the form of metadata, references to the cover image, and a link to the article
• Show Details - sends the contents of an individual Instructable

Heres the base URL plus the path for the Get List endpoint.

URLs can also contain queries that add specificity to a request. For example, requests made to the Get List endpoint can include query strings specifying the number, offset, sorting method, and type of Instructables returned (see green brackety looking thing in the screenshot).

Query strings are placed in a URL after a "?" and tacked together with "&"s.

Requests can be sent to a URL endpoint via a web browser - you do it every time you type in a web address - but there are other, more powerful ways of interacting with APIs. More on that in the next section.

Note: I use a Mac and have no experience using the command line on PCs - sorry Windows users!

Here's our Get List URL from the previous page - https://devru-instructables.p.mashape.com/list?limit=20&offset=0&sort=recent&type=id. Hopefully, upon receiving a request to this endpoing the server will respond with a list of Instructables, like in the example Mashape provides (screen shot above). Click it and see what happens!

Wahn Wahn Wahn Wahhhnhnhnhn - get something like this?

Two problems - 1) presumably, you haven't yet registered for an API key, and 2) you can't pass you're API key to the server via the browser.

API keys are sometimes required so that API user can be monitored and the rate at which they make requests can be limited.

Let's take a look at the screenshot below. First, you can see CURL is selected from a list including some names you might recognize as popular programming languages. Mashape provides examples for making requests to the API via several platform, and we're looking at CURL, a command-line tool (for Mac users, that means the Terminal).

On the second line of the request example you can read '-H "X-Mashape-Key: "'. The "-H" stands for "header", and everything after it will go in the header of the request sent through CURL. The header is part of the web request made to the URL that we can't set when we make our request browser. If we copy and paste the request exampe into the command line as is, we get a response in the terminal like this.

"Invalid Mashape Key" because we tried to pass "required" as a key. To get your key, you'll need to make an account at Mashape.com. Once you do - you can replace "required" with your unique API key, and you'll get a response that looks something like this.

Now you can big chunks of Instructables data on demand - the question is, what to do with it? That's up to you!

I decided bubble charts would be a cool and different way of looking at Instructables content. Without going into too much detail, I wrote a node.js server that makes a request to the unofficial API, parses and buckets and the Instructables data from the API response, then sends the restructured data to a front-end application that uses D3.js to size and position bubbles by number of views. Phew!

Good luck, and thanks for reading!

Nothing to see here, just screen shots images for linking to from previous sections. Thanks for reading!