What Is an API Endpoint? (And Why Are They So Important?)


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 that APIs and API endpoints bring to your website or product.

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 located at the API endpoint.

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

Download Now: Free HTML & CSS Hacks

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

For two software applications to integrate over the internet, one application — called the client — sends a request to the other application’s API. The client may request a resource from the app’s database or ask to perform an 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 the status of the request (e.g., completed or denied) and any resources requested by the client.

diagram of apis and api endpoints in the API request/resposne process

APIs typically allow access to many different resources on a server. For example, a social network’s API might let clients retrieve and modify 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 correct endpoint. In their requests, clients specify an endpoint as a URL. This URL tells the server, “The resource I want is at this location.”

The process is similar to how you access web pages in a browser. Web browsers load web pages by sending a URL to a web server, and the server responds with the requested page. Similarly, the client needs the right endpoint URL to request a particular resource from an API.

Endpoint vs. API

It’s important to note that endpoints and APIs are different. An endpoint is a component of an API, while 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 users know how to access the resources they need. But what do these endpoints look like in practice? Let’s see some real-world examples from leading platforms.

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, say you want your website to stream public tweets in real-time so your visitors stay informed on a specific topic. You can use Twitter’s filtered stream endpoint, whose URL is https://api.twitter.com/2/tweets/search/stream.

We’ll look at the filtered stream endpoint in more detail later in this post.

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, you can access any album in the Spotify 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

The YouTube 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 are requesting the video from YouTube’s API.

Another way to get videos through YouTube’s 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 you ask about APIs is: Why do so many businesses share their data openly, for free?

Most often, the answer is scale. As companies grow, the staff within those companies realize they have more ideas than they have the time and resources to develop them. It’s typically easier to work with other external companies that specialize in these ideas than build them in-house.

By creating APIs, a company allows third-party developers to build applications that improve adoption and usage of its platform. That way, a business can build an ecosystem that becomes dependent on the data from their API, which often leads to additional revenue opportunities.

Take HubSpot APIs as another example: By exposing our software’s functionality and data through APIs, developers can integrate their applications with our technology, resulting in an app ecosystem that increases our reach and makes things much easier for customers who wish to use other applications alongside HubSpot.

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 four 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 the Twitter API’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’ll 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 which is available 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 being 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.

Editor’s note: This post was originally published in September 2021 and has been updated for comprehensiveness.

New Call-to-action




blog.hubspot.com

Leave a Reply

Your email address will not be published. Required fields are marked *