A publisher’s guide to APIs

API is one of those acronyms you hear bandied about. “APIs”, people say, “are vital. Vital!” But if, as you fervently nod in agreement, you’re thinking of another acronym — “WTF?” — then this article is for you.

“API” stands for “Application Program Interface”, which means “a way to interact with a program”. Actually, the sorts of APIs that people get most excited about nowadays are RESTful APIs. In English, that means “a way to send and receive data between programs on different computers, over the internet”.

If you can get computers to send data to each other, that can be very useful indeed. (It’s why the notion of the internet was so moreish.)

For example, you can get data from Amazon’s computers onto the computer that runs your website, which can display it. Even better, you can get your own computer to look at the data that Amazon’s computer sends you and check if it’s correct — so you don’t have to visit 100 Amazon pages to check with your human eyes. You can get the data of your Twitter feed from Twitter’s computers and display that on your own website — or, even better, you can ask Twitter’s computers to send you every tweet that contains a mention of the next 90 books you’re launching and display them on your website, without you having to look each of them up.

You can write your own API so other computers can access your data, too. You could turn the chapters and paragraphs of your forthcoming book about Edinburgh Castle into data that other people’s computers could get, and they can display it on their own websites, or in an app, alongside their own design, pictures and content.

You probably knew all that. But you might not know how it actually works. First off: what does an API look like?

Here’s the result of a query, or ‘call’, to the Google Books API. Here’s the call that was made:

https://www.googleapis.com/books/v1/volumes?q=isbn:9781909679368

Ooh, that’s familiar! It’s a website location! When a computer queries an API, it’s going to a normal old website location, handing over any username and password that’s required, and fetching whatever’s there, or posting new data to the program.

Click on that link so it opens in Chrome or Firefox and you’ll see that the result of an API call is… data. Structured data, though, arranged in a format that’s more convenient for computers than humans to understand (in this case, JSON). It’s still got English words in it, though, so we’re in with a fighting chance of understanding it. You can pick out “authors”, “title”, “ISBN_13” and so on in all that.

And if you know a bit of programming, you can display that data nicely on a webpage. Have a look at this JSFiddle (which is a handy free tool for fiddling around with javascript and html, as the name suggests):

The Result tab shows the data presented nicely, pulled live from Google Books. The Javascript tab shows how it’s done. Neat, huh?

Now – this is the cool bit. You’re going to run your own API query.

Click here to edit the JSFiddle. Don’t worry – you can’t break anything. You’ll see four panes. The first has the HTML – that’s the language that webpages are written in. The one beneath that has some javascript – that’s a language that can perform actions without having to refresh the browser. At the top of the next column is the CSS, used for styling a webpage (and this pane is blank – we’re including a style library called Twitter Bootstrap, automatically). And beneath that we have the result – exactly how the code looks on a web browser page.

Find the line in the Javascript pane that reads:

$.getJSON("https://www.googleapis.com/books/v1/volumes?q=isbn:9781909679368", displayBooks);

and change the text isbn:9781909679368 to something of your choice. So: say you want to search for books about quilting. Change it to this:

$.getJSON("https://www.googleapis.com/books/v1/volumes?q=quilting", displayBooks);

Now click on Run, top left. And see what happens in the results pane! You have made a little scrolling AI all about quilting. Try something else: churches, or snow, or programming. Tinker with anything else on this fiddle and see if you can use other bits of data from the API.

So well done: you’ve had a tinker with the Google Books API. There are loads of APIs out there – from Flickr, LibraryThing, Goodreads, Open Library, and Consonance, of course. Here’s a list of 53 of them. The possibilities are endless and it doesn’t take long to learn enough code to be in control of the world’s data.

Exciting, isn’t it?

Originally published on BookMachine, January 2015

Are your current systems sabotaging your growth ambitions? Are you hungry to implement new business models, but concerned you lack the strong administrative foundations needed for innovation?

We're always amazed at how resigned publishers have had to become to the low bar in publishing management systems. Demand more.