Interacting with an API for the first time is like trying to get a ham and cheese sandwich from a dog.

Imagine you’re visiting your friend’s house and they have a dog. Your friend claims he has trained his dog to get him anything he wants from the fridge. You’re feeling hungry, so you ask the dog to bring you a sandwich.

‘HEY DOG BRING ME A HAM AND CHEESE SANDWICH’

The dog does nothing. You tell your friend he is a liar. Your friend laughs and says ‘Oh! He’s a German Shepherd, he only knows German.’ Weird.

He gives you a book and walks away. You look through the book. It’s all in German. None of it makes sense. But there are some English words! GET. POST. PUT. DELETE. You manage to piece together two words.

GET. FOOD.

Still nothing. At the bottom, your friend has written an example.

‘WWW.FRIENDSHOUSE.COM/GREGORY/GET/FOOD/CHICKEN&id4’.

You read it aloud, and Gregory goes to the fridge and brings you a whole chicken. After some more searching, you find the word SANDWICH.

‘WWW.FRIENDSHOUSE.COM/GREGORY/GET/FOOD/SANDWICH’

Once again, Gregory goes to the fridge, but this time brings you a menu. You see the word Ham and Cheese. Its ID number is 3.

‘WWW.FRIENDSHOUSE.COM/GREGORY/GET/FOOD/SANDWICH&id=3’

Gregory goes to the fridge, gets your ham and cheese sandwich, and oddly with the dexterity of a human, barks at the sandwich, smooshes the ball into the size of a ping pong ball, barks at it a couple more times, and gives it to you.

Congratulations you have successfully gotten data (a sandwich) from an API (a dog)!

SO, WHAT IS AN API?

In the broadest sense of the word, the dog is essentially an API. He is an interface between you and the database (fridge) that provides a service of retrieving information (food). Even though you know what you want, he will only get you your sandwich if you ask him the right question. However, being able to communicate with a dog is difficult because not only does the dog no concept of natural language, but he can also only respond to the words he has been taught. However, once you ask the right question, while you do technically get a sandwich back, the sandwich needs some managing (e.g., parsing) before you can eat it.

HOW DO I INTERACT WITH ONE?

  • Read the documentation

The documentation (phrasebook) is the first thing you should read. Like dogs, every API is different. And while most dogs know the same commands, the specific way you say the command may vary. A well-documented API will not only list the valid commands you can ask but also give examples of how those commands are used.

Note: if the documentation isn’t detailed enough, it may be up to you to experiment and try out different commands and adjust accordingly.

  • Deconstruct the example call

Typically, the documentation will provide some sort of example command. If you’re lucky, the example will fit your exact use case with minimal to no changes. Otherwise, it is up to you to deconstruct the example call and swap out the relevant parameters.

You could think of the API URL as folders within folders or just a general hierarchy of information. Alternatively, your friend’s house (base URL) houses his dog Gregory (endpoint). In most cases, everything after the endpoint you can consider a command for the endpoint. This part is the part that we should change.

  • Changing the API call

When we asked the dog for a chicken, there was an end tag of ‘&id4’. Even without good documentation, we can infer certain aspects that can be changed. From this, we can assume that the &id refers to the specific item ID and that the category chicken potentially has more than one item (hence the need for an ID number).

If we change the ‘&id=4’ to ‘&id=3’ we MAY get another chicken item, but we also may not. If you don’t know the specific item ID, you will have to query the API for some more information such as a list of records (menu).

Maybe you will have to query WWW.FRIENDSHOUSE.COM/GREGORY/GET/FOOD/ to get a list of foods. Or you could try to go straight to WWW.FRIENDSHOUSE.COM/GREGORY/GET/FOOD/SANDWICH which may give you a list of sandwiches available. Ideally, the documentation helps you figure this out, if not, it’s trial and error.

  • Deal with the output

In most cases, the output you get will be gibberish with the occasional familiar word scattered throughout (depending on the output format). However, since this process can be reasonably annoying to do so in my next blog I will be going over how to parse JSON retrieved from an API.

Kevin Prescilla
Author: Kevin Prescilla

As a late-stage PhD candidate, Kevin’s appreciation for data analytics grew during his studies into poultry nutrition, or as he calls it, “chickens”. It was this appreciation which spurred his decision to change career paths and ultimately led him to apply to the Data School. In his spare time he enjoys powerlifting – ever challenging himself to beat his last max weight - as well as all kinds of gaming, from board to PC. If Kevin could go anywhere in the world, where would it be and why? Well, the answer is Antarctica, as he is fascinated with how people can live and survive down there (although some might argue because it’s the furthest place you can go on Earth from a chicken).