Structure of a Query

View slides for this section

A query has a few core components:

• endpoint
• path
• query parameters

Every API has an endpoint which is like providing an address to the server. This is the first piece of information REST expects you to have. For example, if you wanted to get data from the Numbers API (which serves trivia about numbers) through an API call, the endpoint would be: http://numbersapi.com.

The path tells the server which data you are most interested in and query parameters are a way to further specify what you want. Query parameters are not a part of the REST architecture but are commonly used.

A query doesn’t have to lead to only one thing. It’s also possible to batch your requests by indicating that you are interested in more than one piece of data. For the Numbers API this means you might be interested in facts about multiple numbers.

This is just the tip of the iceberg! A lot more is possible with APIs and we will touch on next steps through our activities.

Case study: Querying The Cat API

TheCatAPI is a free web API with information about cat breeds and a database of cat images. The API can be used to search the database, display cat images, upload new images, and tag your favorites. In this activity we’ll use the API to return information about and display a series of cat images.

The basics: one random cat

Open a new browser tab or window. Copy the URL below into the address bar and hit enter.

Input

https://api.thecatapi.com/v1/images/search

The API call returns a JSON string with information about one random entry in the cat image database. For example:

Output

[{"breeds":[],"id":"MTk1ODY2Mw","url":"https://cdn2.thecatapi.com/images/MTk1ODY2Mw.jpg","width":640,"height":480}]

To view the image, copy the URL portion of the JSON string into the address bar, then hit enter.

Getting specific: query parameters

That’s quite a bit of work for one random cat image but we can refine results with query parameters. Add a ? to the end of the URL followed by one or more parameters in the format shown below. Note that each parameter is separated by a &.

Input

https://api.thecatapi.com/v1/images/search?breed_ids=rblu&limit=5

This will return a JSON string with information about five (limit=5) images of Russian Blue cats (breed_id=rblu).

Input

https://api.thecatapi.com/v1/images/search?category_ids=5&format=src

This example returns an image instead of a JSON string (format=src) showing a cat in the “boxes” category (category_ids=5).

Mix and match

The API documentation lists the available query parameters and their acceptable values. Below are some examples you can experiment with.

category_ids parameter

mime_types parameter

Limits output to specified file type: jpg, png, or gif.

format parameter

Default output format is JSON, but setting this parameter to src displays the image itself.