Sometimes the simplest element of a system can be the most important. How would the lights in a flat work if there were no light switch? How would you interact with a laptop without a keyboard and trackpad? In the API space, we often take for granted that the public widely understands what an API call is (let alone APIs in general). In reality, this is largely not the case.

An API call can be thought of as a request. You program a request for a piece of data or functionality, and the endpoint you hit returns a result. Today, we’re going to demystify this element of the greater API ecosystem. We’ll dive deeper into what an API is, as well as what an API call is, and how they work in tandem.

What is an API?

Before discussing what an API call is, we should first quickly define what an API is. An API, or Application Programming Interface, is essentially a collection of methods, protocols, and structures that facilitate communication between two systems. Often, software systems are quite disparate in nature, making APIs a Rosetta Stone to translate and coordinate communication.

Another way to think of APIs is to consider them as intermediaries in a negotiation. For instance, when a user requests information from a machine, the machine may have specific rules for accessing that information. When the user makes a request, that request is pushed through the API ruleset, which may include authorization and authentication requirements and specific methods by which data is retrieved. The response is then collected and formulated based upon the internal API rules and is relayed to the requester through an accepted system.

Let’s look at a typical flow to see what this might look like. Let’s imagine that a user wants to retrieve information about a book in a library system. The user will first utilize a GUI, or Graphical User Interface, to submit the request for the book in a predefined format. This request is sent in the form of a request to an endpoint on the local server running an API. The server takes this request, and based upon the rights of who made that request, the nature of the request, and the presence of the data in the system, it decides how to best serve this data. The server will then collate the data into a response package. This response is then sent back through the system to the end-user, rendered through the GUI to the local user in a human-readable state.

This kind of relationship is called a Client-Server relationship and is ubiquitous in the API space. However, that’s not to say there aren’t many more types of relationships. Other paradigms exist, such as Publisher-Subscriber (or PubSub). Regardless of the kind of intermediary communication, all of these types of relationships are still governed by an API.

What Is an API Call?

In our explanation above, we used several terms — like endpoint, call, and client. When an API is utilized, this utilization passes through the system’s exterior through what is known as an endpoint. An endpoint is simply the edge of a system of data that contains a direction to other systems as to how to get what they need. It’s kind of like a road with a large sign saying, “this is where you go in order to get this piece of information.”

Endpoints are typically named by what they do. For example, in our library hypothetical, we might expect the endpoint to be named librarySearch. This endpoint is one of many, but it carries out (at least in an API designed with best practices in mind) a singular function or set of related functions. The librarySearch endpoint, for example, should contain everything a basic user would need to interact with to find something in the library, be it a book, author, or ISBN.

When this endpoint is interacted with, that interaction is called an “API call”. This interaction doesn’t always involve a person interacting with a system — in fact, it is much more common that an API is interacted with by other APIs, machines, or servers. Regardless of who — or what — is interacting with the system, there are a few common paradigms of interaction. The most common method is through the use of the underlying HTTP verbiage system upon which RESTful (or Representation State Transfer, a paradigm of API design) design is based upon.

Of these verbs, the most common are those that align with CRUD, or Create, Read, Update, and Delete. These roughly correspond to the HTTP verbs GET, POST, PUT, PATCH, and DELETE. These verbs tell the web API exactly what you want to do, how you want to do it, and more importantly, what you expect the state of the interacted resource to be.

• GET: I need you to get some information for me
• POST: I need you to create some information for me
• PUT: I need you to update some existing information
• PATCH: I need you to update a part of some existing information
• DELETE: I need you to remove some existing information

API endpoints are structured to respond to these kinds of interactions with specific responses, attributes, and methods. For instance, GET library.com/librarySearch will likely result in some information retrieved from the database without any alteration of the data at rest on the server. PATCH library.com/librarySearch, on the other hand, will actually update the data, resulting in a change on the server-side of the data at rest.

API Call Parameters

It should be noted that an API call is not always just a simple interaction — calls can often carry a lot of information with each request, and developers have made great use of this fact. In many cases, this additional context is often necessary. In fact, it is very uncommon to find a public API that does not use parameters to pass information such as authentication and authorization data to leverage the API internals.

Certain paradigms like RESTful design can pass information through the Header, Path, Query String, or Request Body, resulting in calls that both carry out a primary function and bundle a good deal of information with the request itself. Other paradigms, like GraphQL, can utilize the call to structure the response itself. In GraphQL, the user can state the specific morphology of the response itself through fields and statements within the call, allowing for a kind of “on the fly” mutation.

Ultimately, a call is simply a starting point for API communication. In more complicated architectures, API calls can become much more complex, allowing for security functions, extensibility, and other powers.

Example API Calls

Let’s see what an API call looks like “in the wild.” We can look at some API documentation to find some good examples. In this case, we’ve taken samples from Twitter’s documentation. Twitter has a variety of endpoints, but one of the simplest is to get the followers of a specific user. Since this type of call requests information without updating it, we want to use a simple GET request.

GET https://api.twitter.com/1.1/followers/ids.json

This call alone won’t do anything, of course — this is just an endpoint. We can pass a bevy of parameters to the request. While all are technically “optional” per the documentation, they allow specific functionality on this endpoint. user_id notes the user whose data is being requested, for instance, but you can use screen_name as another more general parameter targeting the same. With a handful of more complex parameters, we get this kind of call:

GET https://api.twitter.com/1.1/followers/ids.json?cursor=-1&screen_name=andypiper&count=5000

This call does a few things. First, it sets cursor to -1, which allows for some basic pagination. The use of screen_name, as aforementioned, targets the user andypiper. The use of count set to 5000 limits the total number of IDs to be returned in a request, which prevents overfetching and allows for more reasonable data use.

Of note, this same request in curl, an alternative request format, would look as follows:

$ curl --request GET 
--url 'https://api.twitter.com/1.1/followers/ids.json?screen_name=twitterdev' 
--header 'authorization: Bearer <bearer>'

$ curl --request GET 
  --url 'https://api.twitter.com/1.1/followers/ids.json?screen_name=twitterdev' 
  --header 'authorization: OAuth oauth_consumer_key="consumer-key-for-app", 
  oauth_nonce="generated-nonce", oauth_signature="generated-signature", 
  oauth_signature_method="HMAC-SHA1", oauth_timestamp="generated-timestamp", 
  oauth_version="1.0"'

$ twurl /1.1/followers/ids.json?screen_name=twitterdev

As you can see, as long as a parameter is defined in the codebase, it can be called to denote a specific function. In the above curl example, parameters are used to pass a header, pass on a generated OAuth token, and define the context around that token.

Conclusion

Sometimes the simplest definitions can be taken for granted in the API space. Understanding what an API is, and what an API call is, is crucial to comprehending the ever-growing complexity of interconnected networks in modern web development. While this is only a basic primer, we hope we’ve done a decent job of introducing it. Was this topic covered in sufficient detail? Let us know in the comments below!