When the marketing industry first shifted from outbound to inbound marketing, many marketers dropped their old roles of content interrupters for new ones as content creators.
But that shift is still producing aftershocks, and to keep up with your competitors today, you need to understand what APIs are, how they integrate with your content strategy, and the social insight they bring to your website.
Don't worry — APIs might seem complicated, but by the end of this post, you'll know how they work and what using them entails.
Here's a brief definition of an API, followed by some key information on how to make one work for your business.
What is an API?
An API, short for application programming interface, is a series of rules. To be even clearer, it is an information middleman. APIs allow for an application to extract information from a piece of software and use that information in their own application, or sometimes for data analysis.
In the plainest terms, an API is a blueprint that enables "your stuff" to talk to and work with "their stuff." Your stuff, in this case, is known as the API endpoint.
What is an API endpoint?
An API endpoint is the digital destination where APIs send requests for information from a web application or server and where they receive a response and access the resources needed to carry out their function.
Sound confusing? Don’t worry — we’ll walk through an example below.
API Endpoint Example
Let’s say you want to stream public tweets in real-time so that you can stay informed on a specific topic of interest or on current trends in the world. Then you could use Twitter’s filtered stream endpoint. Its URL is: https://api.twitter.com/2/tweets/search/stream
Technically, an API endpoint need only be referred to with the end path of the resource URL. The base path, which is common to all endpoints, is https://api.twitter.com. Because that stays the same, there’s no need to keep listing it. You can instead just list the endpoint: /2/tweets/search/stream.
How to Test an API Endpoint
There are several online tools available for testing an API endpoint. For the sake of this post, we’ll walk through how to set up a test using cURL. cURL is a command-line tool for transferring data that supports multiple protocols, including HTTP. It is able to make requests, get data, and send data — making it the perfect tool for requesting information from APIs.
Let’s use an example from Twitter’s own documentation. Say, you want to stay informed on the Twitter API. Then you will want to get tweets from major accounts like @TwitterDev and @TwitterAPI as soon as they’re posted. And maybe you only want tweets that contain links to articles or documentation so you’re getting as much context as possible.
In that case, using the filtered stream endpoint is the perfect choice. But in order for the endpoint to know what kind of tweets to send you, you’ll have to define filtering criteria. Otherwise, you’d just be asking to see every tweet posted in real-time.
Filtering criteria will be applied to the endpoint in the form of rules. To build these rules, you’ll need a set of operators. For this example, you can use two operators — from: and has:links — in order to only see tweets from certain accounts and that contain links. To instruct the filtered stream endpoint to only show tweets from the accounts @Twitterdev and @TwitterApi that contain links, you’d use the following rule: “from:twitterdev from:twitterapi has:links”
To request this information from the filtered stream endpoint, you need to include the correct HTTP request to tell the API what action to take. There are four main options. Take a look at a brief description of each below:
- GET: retrieve a resource
- POST: create a resource
- PUT: update an existing resource
- DELETE: remove a resource
For this example, you’ll use the POST request. 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 lightweight data format JavaScript Object Notation (JSON). To authenticate your request, you’ll have to replace the placeholder text $BEARER_TOKEN with your app’s unique Bearer Token, which can be generated 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:twitterdev from:twitterapi has:links"}
]
}'
Why are APIs important?
One of the first questions many marketers ask is: Why do all of these businesses share their data openly, for free?
Normally, the answer is: scale. As software companies grow, the staff within those companies quickly 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. In 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.
How to Use an API
Understanding the value of a particular API is essentially about understanding what information is available through an API and how it can be accessed. To find out what a particular API can do for you, you can do one of two things.
- Ask a web developer to look at an API and discuss it with you.
- Do the research on your own. If you don't have access or budget to use a web developer, this is an appealing option. But don't panic — many online services have good API documentation.
API Documentation
Let's take a quick look at Twitter's API reference index as an example.
Much of Twitter's growth has been because of outside developers, and the first Twitter API started as a basic wiki. Since then, it has evolved into a detailed index of APIs that a savvy marketer can use to determine what information might be available to a developer in the form of an API — and how to include this API on your website.
Looking at the screenshot above, you can see there are multiple categories of information available to outside developers. Once you select an API you're interested in, you can click on it to see what information is available through this API. Check out Twitter's Tweet Timeline API endpoint below.
In the API documentation above, Twitter's Tweet Timeline API explains how you can take a brief collection of recent tweets from a specific user's timeline and display them, in clickable form, on your own website. The API documentation includes tweet volume limitations, the API's resource URL, as well as what you can and cannot choose to display through this API.
Applying the API to Your Website
If you add the API's resource URL to the backend of your website, it'll return the information you called for to the frontend of your website. Here's what this looks like on the New York Road Runners website, helping them promote the New York City Marathon (with a few custom design modifications):
You can also check out the HubSpot API documention to see how you can build applications and integrations using data from HubSpot.
One last caveat: In order to officially use a developer's API, you might also need to be assigned an API key.
What is an application programming interface (API) key?
An API key is the unique identifier assigned to an API user, indicating they're allowed to use the application programming interface on their website. Many developers require you to request this key before using the API, while others may assign it to you upon your first API request.
Think of your API key as your authentication token, declaring you a member of a developer's community. In effect, this token identifies what you're using the API for, and verifies that you've been given permission to carry out this project by the API's owner.
Rest assured, your API key does not give the developer access to personal information about you.
APIs as a Marketing Platform
Marketing in an inbound world is about companies developing useful applications and services to sustain customer retention. Brands will 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.
API Examples
Understanding what information is available through an API will help your determine if it is worth working with a developer to pursue the project further. Here are two examples.
Twitter Mentions
If you wanted to show tweets on your website that included mentions on Twitter to articles from your blog, you'd need to understand if you could request tweets with only specific URLs from the Twitter API.
YouTube Video Embedding
When you right-click a YouTube video on youtube.com, and select "Copy Embed Code," you're essentially requesting to use YouTube's API on your website. YouTube makes it easy for the public to embed YouTube videos to play directly on other websites.
API Terms of Service
No matter the project, it's critical that you actually read and understand the terms of service for an API you're considering for your website.
Most APIs have certain usage restrictions. If you don't take the time to understand the restrictions of an API you're interested in, you could invest more time and money in developing a marketing asset that's rendered useless once the API provider determines you've violated the API's terms of service (and revokes your access).
For this reason, most APIs have "call limits."
What is an API call?
An API call, also known as an API request, is an instance of a website owner "calling" for the use of a developer's API. Saving the API, logins to the developer's website, and queries about the application all count as API calls.
With this in mind, an API call limit is the number of times you can request information about an API from a web service within a given time period. Again, please read the terms of use for any APIs you are thinking about using. These documents should clearly detail any limitations as well as appropriate use of the program.
The Future of APIs in Business
Developing on the APIs of existing web services is only the beginning. 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 their customers can develop applications as a result.
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. Obviously, this concept could cause hurdles for some organizations, especially from the legal department. It's up to you to find out which APIs are most valuable and how you can lawfully and sustainably use them.
Editor's note: This post was originally published in March 2013 and has been updated for comprehensiveness.
