An Introduction to the Goodreads APIs
GET going!
Building Your First GET
Let's start using the Goodreads API with a simple GET query. First, you'll need to get your developer's key if you haven't already done so!
Our first use of the API will return a number, so we won't be dealing with JSON or XML parsing just yet. This web app will take an ISBN number (10) and return the Goodreads Book ID number. As you'll see from their API lists, many of your queries of their database will require use of their internal ID numbers, so this is a useful piece to know before going further. In order to start with an ISBN number, first pick one of your favorite books, and look up its ISBN using the link below. Now that we have our developer's key, and an ISBN to get us started, let's try the simplest of queries by grabbing the specifics on our desired query from the Goodreads API site itself:
As we can see from this, we have an example link, the basis of our request to Goodreads's API: "https://www.goodreads.com/book/isbn_to_id". As it indicates, it's just a sample URL, if you follow this link, it will bring you back to the general site. Our actual code is going to need to look more like this:
This is almost the simplest request of an API you can make! When you replace the developer key and a chosen ISBN with your values and run this, you should get an alert
with the Goodreads Book ID. You can verify this is correct by going to the chosen book on the Goodreads site, and looking at the URL. You will see this ID number in the URL before
the title as below:
Another, simpler way to test GET requests is right in your browser! The components are indicated broken out below as parameters in the method explanation:
- Base sample URL (in this case "https://www.goodreads.com/book/isbn_to_id"),
- Followed by a "?" to begin the GET request,
- Then each parameter (in this case your developer's key) as a matched pair (here "key=" and the requested value), with each of these pairs separated by an "&,"
- And ending with isbn in this case. Note with one isbn you must enter the singular isbn, matching the provided case!
- NOTE: you'll need to experiment, as not all of the methods in the documentation are detailed completely. Some leave off the key (and it is always required), and some falsely indicate OAuth is required when it is not, or leave it off when it is. When in doubt, consult the Developer's Forum (see OAuth) at the end of this tutorial for more info!
You can post the assembled URL line (with your developer's key and ISBN in this case) right into
the browser and you should get the response back:
Now let's take another look at the client-side JavaScript code we can use instead:
After the initial variables holding your key and the ISBN, a new variable is opening an Ajax request (Ajax was formerly an acronym for "Asynchronous JavaScript and XML" but is now typically lowercase as XML is often not even involved). This object (XMLHttpRequest) communicates with the server, sending and receiving information in a number of formats. In this case, we're just getting a number back (Goodreads internal book id), but we'll follow up with JSON and XML formats, both of which are used with the Goodreads API.
We use this object to open our request, with the type ("GET") the the URL, and a 'true' to indicate it is asynchronous (a 'false' here indicates it is synchronous, or we stop and wait until it is loaded).
As indicated in the comments, next we add a listener, which will run as soon as the object has loaded,
(hence the asynchronous nature of the call). If we get a good response from the server, we will alert
the number. Otherwise, the console will be logged the error response.
The final line is the send of the request!
So, this is the most basic GET we can run, right? What use is this? Well, you might need a request
like this initially within your script to get the Goodreads ID for any number of other requests. But let's step things
up a bit. In our future calls, we're going to want to deal with a variety of data, not just numbers.