This “Introduction to APIs” was developed by Owen Stephens (owen@ostephens.com) on behalf of the British Library. This work is licensed under a Creative Commons Attribution 4.0 International License http://creativecommons.org/licenses/by/4.0/. It is suggested when crediting this work, you include the phrase “Developed by Owen Stephens on behalf of the British Library”
Purpose of these exercises
The purpose of this set of exercises is provide an insight into what it is like to work with an API on the web. Specifically the exercises here will introduce:
- the basics of how APIs work
- what questions you need to ask and challenges you can face when using an API to build an application, and so…
- what things you need to consider when providing an API for people to use (or selecting a system that offers an API)
While the exercises here work, they are not a genuine attempt to build a useful application with an API. If you are interested in using APIs you may want to consider looking at the lessons and tutorials available from:
How APIs work
There are many different types of API, and they don’t all work in the same way. However, broadly the user of the API (e.g. the developer or the software written by the developer) makes a request to the API, and gets back a response.
A single API may support different types of request. For example, the Twitter API supports a range of requests including:
- search
- status update (i.e. post a Tweet)
- get list of follower
Sometimes these different API requests are called ‘API calls’.
The API will define what information can be included in a request and what information will be sent back in the response (and in what format).
This is where good documentation for an API is essential – it is really difficult to use an API when you are left guessing what information you need to send it and what information you can expect to get back. When assessing an API, assessing the quality and availability of the documentation should be taken into account.
To use an API, you also need to know where to send the request to – when working with web APIs this will be a URL.
Exercise 1: Using an API for the first time
Introduction
In this exercise you are going to use a Google Spreadsheet to display and manipulate an image using the IIIF Image API.
Understanding the API
The API you are going to use is the IIIF Image API. The IIIF Image API is designed to enable you to work with a single image, requesting either the image itself OR information about the image. The IIIF Image API is documented at http://iiif.io/api/image/2.1/.
The IIIF Image API supports two types of requests – the “Image Request” (gets back an Image) and the “Image Information Request” (gets back information(!) about the image – this includes data such as the size of the image and the types of image manipulation that can be requested using the Image Request parameters).
The place you send the request to will depend on what digital library (or other IIIF compliant service) you want to get the image from.
In this first exercise you are going to use the ‘Image Request’ API call. The request to the API is made using a URL, and you can vary the details of the request by modifying different parts of the URL. The parts of the request you can modify are sometimes called ‘parameters’. The IIIF Image Request URI is structured as follows:
{scheme}://{server}{/prefix}/{identifier}/{region}/{size}/{rotation}/{quality}.{format}
Each word in curly bracket { } represents a part of the URL you need to create to make a request to the Image Request API.
You can look at these using an example from the Bodleian’s IIIF compliant service:
http://iiif.bodleian.ox.ac.uk/iiif/image/a1795520-e3c8-44a0-a077-c80a398978b9/full/full/0/default.jpg
You can see how this URL maps to the structured described by the IIIF Image Request documentation.
| Breakdown of URL… | ||
| {scheme} | http | Together these three parts of the URL essentially form the address to which the API request can be made |
| {server} | iiif.bodleian.ox.ac.uk | |
| {prefix} | iiif/image | |
| {identifier} | a1795520-e3c8-44a0-a077-c80a398978b9 | This is an identifier for the digital object you want the API to use as the basis of its response |
| {region} | full | The ‘region’ parameter lets you define whether the API will return the whole object, or just a specific region of the object. In the example ‘full’ is used indicating the whole image |
| {size} | full | The ‘size’ parameter lets you define the size of the image returned by the API. In the example ‘full’ is used indicating the API should respond with full size image |
| {rotation} | 0 | The ‘rotation’ parameter lets you specify if you want the API to rotate the image in the response |
| {quality} | default | The ‘quality’ parameter tells the API whether to respond with a colour, gray scale, or bitonal image. In the example ‘default’ is used to indicate that the API should respond with whichever format is the default for the requested image |
| {format} | jpg | The ‘format’ parameter tells the API what image format to use when it sends its response. In the example ‘jpg’ is used to indicate that a JPEG image should be sent. |
The response you get from a request to this URI is an image.
The key things you need to know to work with this API are:
- The address of the API (the first three rows in the table above)
- The parameters that the API expects in a request (the remaining rows in the table above)
- What the API will send in response to a request (an image)
Now you’ve got this information, you are ready to start using the API.
Going Further
To find out what valid values can be used for each of the parameters in the IIIF Image Request API, read the documentation available at http://iiif.io/api/image/2.1/.
Using the IIIF Image Request API to retrieve and display an Image
To use the API, you are going to use a Google Spreadsheet. A template spreadsheet has already been setup which you will use for this exercise.
Go to http://drive.google.com and login to your Google account. In a separate browser tab or window, visit the following URL:
Click on “File” and choose “Make a copy”. You should be prompted to set a name for your copy, and once you click ‘OK’, this should make a copy of the Google Spreadsheet in your own Google account.
You should now have an editable spreadsheet that looks something like:
The way this spreadsheet is laid out is to have one cell per parameter for a valid IIIIF Image request. By filling out the rest of this spreadsheet, and then telling it to send the request to the API, you will be able to retrieve and display an image.
Based on the information you obtained by understanding the API (see above) you can complete the parameters in column B as follows:
- B3: full
- B4: full
- B5: 0
- B6: default
- B7: jpg
You now have all the parameters we need to build the API call. To do this you want to create a URL very similar to the one you looked at above. You can do this using a handy spreadsheet function/formula called “Concatenate” which allows you to combine the contents of a number of spreadsheet cells with other text.
In Cell B8 type the following formula:
=concatenate(B1,"/",B2,"/",B3,"/",B4,"/",B5,"/",B6,".",B7)
This joins the contents of cells B1 to B7, with the appropriate characters in between to make a valid IIIF Image Request URL. Once you have entered this formula and pressed enter your spreadsheet should look like:
The final step is to send this query display the response. Since we know the API ‘request’ takes the form of a URL, and the response is going to be a JPEG image, we can take advantage of the fact that Google Spreadsheets has a special function for retrieving and displaying Images.
To use this, in Cell B9 type the following formula:
=image(B8)
Now, hit enter, and see the result.
Congratulations! You have built an API request, and displayed the response.
Modify the API request to change how the image is displayed
Now you have a working API request, you can start to modify the request to control exactly what image is returned in the response. We have to use valid values for the parameters in order that the API knows how to respond correct.
For example, the ‘Rotation’ parameter controls whether the image is rotated in the API response. The Rotation parameter is a numeric value expressed in degrees of rotation, that is a number between 0 and 360 inclusive. Some images (including the one used in this example) only allow rotations in steps of 90 degrees, so in this particular case on values of 0, 90, 180, 270 and 360 are allowed.
To change the rotation, modify the value of the ‘Rotation’ parameter (in cell B5) from ‘0’ to ’90’.
The value in the ‘Rotation’ parameter can also be preceded by an exclamation mark ‘!’ to request a mirror image version of the digital object.
Try modifying the value of the ‘Rotation’ parameter to ‘!0’
The ‘Region’ parameter defines a rectangular portion of the full image to be returned. This can be expressed in a number of different ways (all described in the API documentation). In this case you are going to display a rectangular area of the image by specifying the coordinates of the top left corner of the rectangle in pixels (a unit of measure for digital images) and the width and height of the rectangle, also in pixels. An example from the IIIF documentation is illustrated here:
In this example, by setting the ‘range’ parameter to “125,15,120,140”, the API will respond with a rectangle from the original image that is 120 pixels wide, and 140 pixels high, starting 125 pixels from the left of the image and 15 pixels from the top of the image.
- Try changing the Region parameter to “1090,860,360,250”
- You can play around with these numbers to show different areas of the original image.
- Change the Region parameter back to ‘full’ to display the whole image again
You have:
- Explored the IIIF Image Request API
- Seen how you can create a request (aka Call) for the API by constructing a URL with appropriate parameters
- Retrieved an Image using the IIIF Image Request API
- Modified the request to control how the image is returned to you
Going Further
This spreadsheet will work with any service which supports the IIIF Image Request API. To try this you can replace the ‘Base URL’ with the URL of the British Library’s IIIF API, and enter an identifier for an image on the British Library server. Try replacing the Base URL and Identifier in the spreadsheet above with the following information:
- Base URL: http://api.bl.uk/image/iiif
- Identifier: ark:/81055/vdc_100004173859.0x000002
This image is part of a digitised magazine. By modifying the identifier you can view other pages from the magazine. E.g.:
- ark:/81055/vdc_100004173859.0x000003
- ark:/81055/vdc_100004173859.0x000004
- ark:/81055/vdc_100004173859.0x000005
etc.
Can you modify the spreadsheet to make it easy to move from page to page without having to re-type the identifier each time?