Marketing in an inbound world is about developing useful applications and services to sustain customer retention. Brands need to move away from intermittently dropping in advertisements to become conduits of consumer communications.

In that process, APIs facilitate the data needed to provide solutions to customer problems. To keep up with your competitors, you need to understand what APIs are, how they work with your content strategy, and the functionality they bring to your website or application.

An API, short for application programming interface, is a series of rules allowing an application to share its data with outside developers. In the plainest terms, an API enables you to take “their stuff” and make it work with “your stuff.” Their stuff, in this case, is known as the API endpoint.

In this guide, we’ll break down what an API endpoint is, the role endpoints play in integrations, and how to start testing them with public APIs (and potentially with your own).

Download Now: Free Intro Guide to HTML & CSS

What is an API endpoint?

To fully understand this definition and where endpoints fit within the API model, let’s briefly review how APIs work.

In order for two software applications to integrate over the internet, one application — called the client — sends a request to the other application’s API. Depending on the API’s capabilities, the client may request some resource from the app’s database, or it may ask to perform some action on the server.

Upon receiving and validating the client’s request, the API performs the requested action, then sends a response back to the client. This response includes any resources requested by the client.

rest API endpoint illustrated in a diagram

Image Source

APIs typically allow access to many different resources. For example, a social network’s API might let clients retrieve post content, user profiles, and images. A news site’s API will allow access to its article content, authors, and media like podcasts and videos. Knowing this, how do clients specify which resource they want to access in their request?

The answer is by using the right endpoint. Clients specify an endpoint (in the form of a URL) in their requests. This says to the server, “The resource I want is at this location.” The process is similar to how web browsers request web pages with URLs — to request a particular resource from an API, the client needs the right endpoint URL.

Endpoint vs. API

It’s important to note that endpoints and APIs are not the same things. Rather, an endpoint is a component of an API. An API is a set of rules that allow two applications to share resources. Endpoints are the locations of the resources, and the API uses endpoint URLs to retrieve the requested resources.

API Endpoint Examples

Developers list all endpoints of their API in the documentation so that clients know how to access the resources they need through the API. But what do these endpoints look like in practice? Let’s see some examples.

Twitter API Endpoint Example

The Twitter API exposes data about tweets, direct messages, users, and more. Let’s say you want to retrieve the content of a specific tweet. To do this, you can use the tweet lookup endpoint, which has the URL https://api.twitter.com/2/tweets/{id} (where {id} is the unique identifier of the tweet).

Now let’s say you want your website to stream public tweets in real-time so your visitors stay informed on a specific topic of interest. You can use Twitter’s filtered stream endpoint — its URL is: https://api.twitter.com/2/tweets/search/stream.

We'll look at the filtered stream endpoint in more detail later on.

Spotify API Endpoint Example

Spotify’s API gives developers access to song, artist, playlist, and user data. For example, if you want to get a specific album from its server, you can access any album in Spotify’s catalog with the endpoint https://api.spotify.com/v1/albums/{id} (where {id} is the album’s unique identifier).

Or, say you want to send a request that makes a user follow a playlist. In this case, send a PUT request with the endpoint https://api.spotify.com/v1/playlists/{playlist_id}/followers (where {playlist_id} is the unique identifier of the playlist).

YouTube API Endpoint Example

YouTube’s API, among other things, makes it easy to embed YouTube videos on any website. When you go to a YouTube video and copy the embed code, you're essentially requesting the video from YouTube’s API.

Another way to get YouTube videos through the API is by requesting them from the endpoint https://www.googleapis.com/youtube/v3/videos, which returns a list of videos that match the parameters you specified in your request.

Why are API endpoints important?

One of the first questions many marketers ask about APIs is: Why do so many businesses share their data openly, for free?

Usually, the answer is scale. As software companies grow, the staff within those companies realize they have more ideas than they have time and resources to develop them.

By creating APIs, companies let third-party developers create applications that can improve usage and adoption of the main platform. That way, a business can build an ecosystem that becomes dependent on the data from their API — a dynamic that often leads to additional revenue opportunities.

As we’ve learned, endpoints are central to APIs, literally. They’re the point at which the client and the server communicate. Without properly structured and functioning endpoints, an API will be confusing at best and broken at worst. As you make more data available through your API, it’s vital to ensure that each endpoint provides valuable resources for clients.

How to Test API Endpoints

When discussing web APIs, we’re usually talking about a type of API called a REST API, which utilizes HTTP methods that tell the API what action to take. The most common HTTP methods in API requests are:

  • GET: retrieves a resource
  • POST: creates a resource
  • PUT: updates an existing resource
  • DELETE: removes a resource

Let’s see how to make a request with Twitter’s filtered stream endpoint. Requests are formatted by writing the HTTP method, followed by the endpoint URL. So, a request to the filtered stream endpoint will look like: POST https://api.twitter.com/2/tweets/search/stream.

Now, imagine you want to stay informed about HubSpot on Twitter. You’ll want to get tweets from the @HubSpot account as soon as they’re posted. Also, let's say you only want tweets that contain links to articles.

In that case, using the filtered stream endpoint is a perfect choice. But, in order for the API to know which tweets to send you, you’ll need to define filtering criteria. Otherwise, you’d just be asking to see every tweet posted in real-time (gulp).

We can apply filtering criteria to the endpoint in the form of rules. To build these rules, you’ll use a set of operators. For this example, you can use two Twitter API operators — from: and has:links — to only see tweets from certain accounts that contain links. To instruct the filtered stream endpoint to only show tweets from the accounts @HubSpot that contain links, use the following rule: from:HubSpot has:links.

In your request, you’ll use the HTTP method POST. In addition to including the rule mentioned above in your request, you’ll include the content type and authorization. Below the content type is defined as “application/json” so the request is rendered in the data format JavaScript Object Notation (JSON).

There are several online tools available for testing an API endpoint. Here we’ll use cURL, a command-line tool that supports HTTP. It can make requests, get data, and send data, so it's a great tool for testing APIs.

Here’s what your request to the Twitter API should look like on the command line. To authenticate your request, you’ll have to replace the placeholder text $BEARER_TOKEN with your app’s unique bearer token, you generate in your developer portal.

 
curl -X POST 'https://api.twitter.com/2/tweets/search/stream/rules' \
-H "Content-type: application/json" \
-H "Authorization: Bearer $BEARER_TOKEN" -d \
'{
"add": [
{"value": "from:HubSpot has:links"}
]
}'

The Future of APIs in Business

We live in a world that now expects open and available content for all — the natural progression of this is for publishers themselves to release their own APIs so that customers can develop applications with them.

API sharing applies to all businesses: not just those that are web-based, but rather anyone who has a web-based tool or component of their organization. Of course, this concept will cause hurdles for some organizations, a major one bring getting everyone on the same page of how APIs work.

It’s easy to get bogged down in the technical jargon of APIs. However, when applied to real-life cases, it’s easier to understand how and APIs work the way they do. Hopefully, you now have a better grasp of one of their key components, endpoints.

New Call-to-action

 css introduction

Originally published Sep 20, 2021 7:00:00 AM, updated September 20 2021

Topics:

Application Programming Interface (API)