API calls explained

Introduction

If you have been involved in any capacity with big data, you probably are aware that APIs are all the rage now. You probably heard the word being thrown around a lot, along with various other API specific jargon. API calls, REST APIs, Streaming APIs and more. It is no wonder such jargon can leave many uninitiated battling with confusion! So, today we will try to chip away at this cloud of confusion by explaining exactly what is an API call.

APIs are an incredibly significant part of today’s world, as so many of our daily interactions occur online, where we use our device to communicate with somebody else’s device. The growing use of device and internet-based communications have led to businesses spending more than $590 billion each year on integrating APIs into their systems.

In this article we will cover what exactly is an API call and why it is so important. In order to answer these burning questions succinctly, we will also cover the basics of what APIs are in the first place! If that is something that interests you, grab yourself a cup of tea, or coffee and read on! If you are in a rush however, why not check out the short answer below?

What is an API call – the short answer

An API call is a process by which a request is sent to a server. It is how an exchange of data, or information occurs between the user’s device and recipient device. An API call usually consists of an endpoint, a header, a method, parameters and a query.

What is an API?

To understand what is an API call fully, let’s first go over what is an API in the first place.

We humans have a whole rule set for communicating with each other. Those rules encompass verbal and non-verbal communications. We know that we shouldn’t interrupt whilst the other person is speaking. Humans can also tell that if the other person pauses for just long enough, it is now our turn to speak. We even interpret the inflection at the end of the sentence as a question, even though we can’t visibly see any question mark!

Well, API is just that, but for electronic devices such as servers, laptops and mobile phones. Essentially, API stands for “application program interface” and it is a communications framework for machines. APIs are a means of communicating between machines. It is a rule set governing how exactly one machine can communicate a specific request to another. You can use such a framework to precisely request some data from another machine, or you can provide your own data for another machine to work with and state what you would like to be done with the data.

In fact, you probably use multiple (albeit possibly hidden behind user-friendly interface) APIs every single day! Did you look something up on Google Maps? You used an API. Did you download that game you were waiting for so long from Steam? You also used an API. Did you go on Spotify? Yep, you get it.

 

In all of the aforementioned cases, your device is requesting information and data from a server operated by the business you were interacting with.

How Do APIs Work?

For example, if you looked up your favourite Café on Google Maps, you accessed google maps application, which on your behalf requests information from the Google database according to your specifications. In other words, the app uses API to request information on the location of the café along with a couple of other details like reviews from the Google server.

All of these examples are using APIs that are hidden behind user interface. However, a lot of APIs are used by developers to pull necessary data and to use said data in their code scripts or even their apps. This is why developer APIs are so useful! Since APIs are fairly new in the developing space, they are not as standardised. This means you may hear of many API types floating about each with unique advantages and disadvantages.

Some examples of API types include REST, SOAP and GraphQL APIs. These as mentioned come with their own sets of advantages and disadvantages, but that is a great topic for another post. So, not only do we have different API types, each individual API works slightly differently from one another. It is because different businesses structure their APIs differently. We explore this concept a bit more in the guide for working with GraphQL APIs in Python.

What is an API Call?

Now that we briefly covered what an API is, we can get down to business. So, what is an API call?

Well, to answer this, let’s think back to the example where we looked at searching for your favourite café on Google Maps. Here, we essentially made an API call. An API call is a process by which we exchange specific information, or data with another machine which stores it. Let me explain. When we searched for the café on Google maps, the Google Maps application made an API call on our behalf. It went through a specific process to specify what information we need, ensure the request goes to the right place and to pass any necessary security checks. Then Google Maps server, serves us the content as a response.

API Call Components

Now that we know what is an API call, let’s have a look at what goes into making an API call. A vast majority of API calls contain:

• an endpoint
• a header
• a method
• a query

This is true for most types of APIs, as well as most programming languages that you could use to make an API call.

Endpoint

Broadly speaking, an endpoint is the “place” where your request needs to go. Imagine you are sending a good old snail mail letter to someone requesting information from them. You need to make sure the letter gets to the right address and person. When making an API call you need to ensure your call goes to the correct server/ group of servers.

The way we specify an endpoint is of course slightly different to the way we specify an address. For most API types, we specify endpoint with a portion of URL like in the example below.

It is always important to ensure you consult the API documentation when specifying an endpoint. This is because some APIs use a single endpoint for all requests, whereas others use multiple endpoints. In the case of multiple endpoints, usually different types of requests utilise different endpoints.

Headers

Most API calls you make will require headers. Headers are almost like disclaimers or notices you see in your gym before you access it. Before you change in the locker room, you will usually see some sort of disclaimer saying that you are responsible for the safety of your belongings. The gym is conveying the initial information before you access their service.

Headers are very much like that. Headers are essentially a set of initial options, or information you convey to the recipient of your API call, before they even process it. This is the space where you will usually need to provide an API key for authorisation of your request. It is also the headers where you might need to provide the format in which you want the supplied response.

The way we specify headers will differ depending on the API itself, as well as the programming language you are using to make the call. This also extends to what information you need to include in the header. Consulting API documentation is once again crucial, no matter how much you might hate reading manuals! See an example of a header for Charitybase API call in Python below.

Method

When making an API call you will need to specify a Method. A method is a way we can specify what action we want to take. Imagine walking into a pawn shop. In the shop you have two main actions you can take. You can buy, or you can sell. When you approach the person working at the till you need to make it clear whether you want to buy or sell for them to be able to help you.

In the very much same way, when we make an API call, we need to state clearly what type of action we want the recipient machine to take. Methods can be referred to as verbs, as we literally use verbs to determine methods! You will see what I mean in a second.

There are a couple of methods you can specify, but I will go over the main three methods. The rest of the methods are mostly slightly modified versions of the main three methods. These are the three main methods:

• GET – This method is simply used to request the server to supply data/information to you according to your specifications. For example, if you search a location on Google Maps, you are likely performing a GET request, where Google Maps supplies requested location data to you.
• POST – The request is used in situations where you want to send data, or information to the recipient of your API call. For example, when you created a Facebook account, the Facebook application made a POST request to Facebook servers, supplying them with your name, email, password and a few other pieces of data they need.
• DELETE – The method simply requests the recipient server to delete a piece of information, or data. This method could for example be used when you decide to delete an account and tick the box asking the server to delete all the data it holds on you.

See the below example of a method for Charitybase API call in Python.

Query and Parameters

So now that we specified everything else, we can use a query and parameters to exactly specify exactly what we are requesting. Let’s go back to a pawn shop example. We used a method to specify we wish to buy something. A query would be us specifying exactly what item we wish to buy.

Same way in an API call we would use a query with GET method to specify exactly what data we require. Now this can be a bit tricky, as queries vary wildly between API types and between individual APIs. Therefore, definitely make sure you consult the documentation for a given API.

For example, using a GraphQL API you may need to use the API specific schema (structure) to build your query, whereas in REST API you might specify the required data by modifying the endpoint URL and passing some additional parameters separately.

See the below example of a method for Charitybase API call in Python.

Full API Call Example

I hope you found this article helpful! If you are interested in learning how to use API calls, why not check out our very own definitive guide for making GraphQL API calls in Python? If you just want a quick glance on what a code for an API call might look like, check out the full API call example below!

import json
import pandas as pd
import requests
from pandas.io.json import json_normalize
from pandas import DataFrame

# set query

query = """ query {
  CHC {
    getCharities(filters: {
      #search: "The Trussell Trust"
      operations: { every:["302"]}
      causes: {every: ["105"]}
    }) {
      count
      list(limit: 30
      skip: 0) {
        id
        names {
          value
          primary
        }
        activities
        operations {
          id, name
        }
        #causes {id, name}
        contact {address, email, phone, postcode, social {
          platform
          handle
        }}
        finances {
          income
          spending
        }
        registrations {registrationDate, removalDate}
      }
    }
  }
}
"""

# set endpoint

url = 'https://charitybase.uk/api/graphql'

#set headers

headers = {'content-type': 'application/json',
           "Authorization": "Apikey API KEY"}
# set method

r = requests.post(url, json={'query': query}, headers=headers)