What is an API call?

What is an API call?

An API call is when a client sends a request to an API, causing the API to get the required information from an external application, server, or program, and deliver it to the client.

You might also see an API call referred to as an API request. They’re the same thing.

The API is an intermediary, just like those old switchboard operators from the movies. If you want something, you’ve got to go through them.

1940s you: “Hello, operator? Can you connect me to a local catering company? I’m having a party in a couple of weeks and I’d love to get the food arranged.”

Operator: “Hold please while I connect you.”

You again: “Hi, can you cater a party for me?”

Catering company: “Sure – just a few questions and we should be able to get that sorted out for you.”

Why API Calls Matter?

Without API calls, you couldn’t interact with external applications via an API. The alternative would be to build any functions you needed from the ground up. This requirement would significantly slow down the development of most digital products. Many projects would simply be unviable, with the costs associated with development becoming unaffordable.

A lower barrier to entry means more exciting projects can get off the ground by making the most of work that’s already been done. Instead of recreating something that already exists, developers can create something new.

API calls have made the rich ecosystem of applications we have today possible.

API Call Examples

At this point I’d love to throw in a statistic about how many API calls are made each day. But frankly, it’s impossible to know. The number is almost certainly too large to fit into a blog post and I won’t waste your time with a guestimation.

With so many API calls being made, picking representative examples is tough. Instead, here are some notable examples to show how API calls work in practice.

What is an API?

API stands for Application Programming Interface. APIs are how different pieces of software talk to each other – they’re the messengers of modern programming.

This is useful for most web development because it means developers don’t need to spend time and money reinventing the wheel every time they want something round that rolls.

But APIs are especially useful in an architecture like Jamstack where websites are built from a greater variety of separate parts.

The result is often a ‘custom stack’ made of different technologies. These are connected via APIs that web developers use to achieve their specific goals without being locked into any particular solutions.

In our earlier real estate website example, we talked about how the developers used a map built with JavaScript to help users understand the location of real-world properties.

Those developers didn’t need to build a maps platform themselves because they could connect their site to an existing one – the Google Maps Platform – with an API.

Twitter API

You want to display a feed of tweets on your webpage. But you don’t just want to display any tweet. You want to show tweets with a particular hashtag. Twitter calls this a filtered stream.

A filtered stream is a feed that only shows tweets that meet certain rules. Because Twitter wants greater market penetration and exposure, they make it as easy as they can for developers to do this. For example, by publishing a free guide to setting rules for your filtered stream.

Another benefit for Twitter of offering an API is that they can charge extra for developers who want more features. Twitter’s elevated access level lets developers set 25 rules rather than the 5 you get under the free version. APIs therefore also give established tech companies an extra way to monetize their products.

Getting started with the Twitter API is straightforward:

1. Sign up for a developer account
2. Create a project and associated developer app as part of the onboarding process
3. Save your API key and tokens, ideally in a secure password manager
4. Make your first API request

The result is that website owners are able to display content from Twitter right on their pages. There are a range of possible benefits. eCommerce businesses can display social proof, with tweets featuring praise for their products, for example.

Google Maps API

You’re the cofounder of a startup building a brand new social media platform – very ambitious of you! – that enables real world meet-ups of people who share similar interests.

You’ve got enough coding for your developers to do already. Although the maps are an important feature because they help people find their meetup without needing to exit the app, you only have so much money to spend. You’d rather your devs spend their time and effort building truly original features.

And there’s no need to reinvent the wheel here. Especially when keeping up with the kind of features a titan like Google can develop over time is going to be next to impossible.

Just like Twitter, Google offers extremely clear and practical resources to get started with their API. In fact, the Google Maps Google Developers page lets you choose among the various features Maps supports, each of which has its own API.

This is helpful, as you can reduce the complexity of your application by only making use of the Google Maps features you need. For example, you may be launching your app in the US only. As a result, you have no need for the Time zones ‘Places’ feature that calculates the proper time zone based on a set of coordinates. So you skip it.

However, you’re extremely interested in using the Google maps ‘Routes’ Directions feature to help users find their meetup. Google offers an API specifically for that.

How to Make API Calls

Specifics of how to make an API call vary, but not hugely. The basic approach is common to most, if not all, APIs.

1. Find the right URI for your API call

Just like with an old-style phone call to a landline, you need to know certain information about who you’re trying to contact. With a phone call, that is (was?) the area code and then the recipient’s specific number.

For an API call, you need the Uniform Resource Identifier (URI) for the application or other digital product you’re trying to connect with via the API. Returning to our earlier example, Twitter’s URI is https://api.twitter.com/. This is also the ‘base path’ – you can think of it like the area code in a phone call.

You can then add the ‘endpoint’ – the details of the specific feature you’re trying to connect to – in a couple of ways to get you the final distance. The simplest is to add it after the base path. For example, the endpoint for Twitter’s filtered stream we discussed earlier is /2/tweets/search/stream. So, your URI should read:

https://api.twitter.com//2/tweets/search/stream

2. Pick a verb

“What do you want?” It’s what people ask when you call them in real life, and it’s what the external software/app you’re connecting to will want to know when the API taps it on the shoulder. You prepare for this question by adding a verb.

There are a large number of verbs to choose from, depending on the need. For example, GET retrieves a resource. DELETE, well, deletes. You’ll include additional information alongside the URI that will give more details about how the task is to be completed.

3. Add a Header

The external application will need to know the kind of response you’re expecting. To signal that, you’ll include a header. Common types include:

• Accept: States the proper format for the response so you can read the information correctly
• Content-type: Kind of the reverse of Accept. It lets the external app know the type of information you’re providing as your request. Specifically, how it’s formatted.
• User-agent: Lets the server identify the entity making the API call.

4. Enter your access token

You’ve seen how there can be different levels of access via an API with Twitter’s different plans. You may be wondering how Twitter regulates and enforces the different permissions and restrictions while keeping track of billing and authorization at a technical level.

The answer is, “access tokens” and “API keys”. These are sequences of letters and numbers that identify the application sending the request. These are added as query parameters.

5. Wait for a status code

The server will send you a status code letting you know whether your request has been successful (a 2XX code) or not (a 4XX code).

The most famous of these codes is arguably 404 Not Found. It’s well known because people who’ve entered a bad request in their internet browser – a common mistake – are treated to a 404 response.

What you need to do next will depend on the code you get. For example, a 403 Forbidden response means you might lack the necessary permission.

APIs are indispensable to modern tech startups

Speed to market is vital for today’s cohort of tech startups. Delays allow faster rivals the space to gobble up market share. As the first company to offer a new type of digital service frequently becomes the dominant player in their space, any tool on hand to get a quality product onto people’s devices sooner is hugely valuable.

As we’ve seen, APIs have this advantage because they let developers make the most of work that’s already been done. Devs can spend time writing new code – rather than duplicating the efforts of others.

The speed and flexibility of APIs is why they’re one of the pillars of Jamstack – an approach to development that emphasises speed, security, and scalability.

Ready to accelerate your development journey? Let us know. We’ll be happy to take a look at your aims, give some helpful feedback, and discuss how we can help you succeed.