You may not know what an API does or even what it stands for. But, you've definitely encountered them. Everyday APIs work behind the scenes to provide you with richer digital experiences.
The movie ticket you bought online, the recipe you shared on Facebook, and the flight you booked on Expedia are all thanks to APIs.
By delivering seamlessly integrated user experiences, APIs present a wealth of business opportunities. But, before discussing how APIs could advance your business, I’ll share what APIs are and why they’re proliferating.
What is an API?
An API, short for Application Programming Interface, is a software-to-software interface. APIs provide a secure and standardized way for applications to work together. They deliver the information or functionality requested without user intervention.
Because APIs do all the heavy lifting, digital experiences remain virtually effortless for end users. Here's a video from Mulesoft that does a great job of explaining the purpose of an API with a restaurant analogy:
Real-World API Example
Say I want to see the latest box-office hit. My first step might be searching where and when it’s playing on an online ticketing site like Fandango.
After typing in my zip code and selecting a date, I click “Go.” Then, voilà, a list of showtimes at nearby theaters appears within seconds. Here’s what it looks like to the end user.
Although I stay on Fandango’s site the whole time, there are multiple applications at work to make my search possible. When I click “go,” the site uses APIs to request access to each theater’s database.
The act of requesting access to information through an API is called an API call. After the API is called, it retrieves the requested information and sends it back to Fandango. Finally, Fandango’s site displays the most relevant results for me.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
You're all set!
Click this link to access this resource at any time.
Why use an API?
Now that you’ve seen an API in action, you can glimpse some of the benefits of this system. By leveraging APIs to access another company’s data, you can extend the functionality of your own product while saving time and money. Teams also use APIs internally so they can access information securely and create a consistent framework for applications to interact.
Now, let’s talk about the benefits in detail. Below, I’ll discuss how APIs support two groups: the folks who use APIs (both directly as developers and indirectly as consumers) and the people who create them.
Benefits to API Consumers
Higher User Satisfaction
Companies want to provide the best experience for their users. Rarely can one product satisfy and anticipate every need and expectation. That is why developers use APIs to extend the functionality of their products.
For example, OpenTable uses the to embed an interactive map on its site. This lets users get directions to nearby restaurants in just a few clicks. If you’re unfamiliar, check out this map of a steakhouse in Indiana.
Allows for More Innovation
Allowing developers — external or internal — to reuse software saves time. This allows them to focus on developing new solutions rather than repeating work that’s already been done.
Let’s revisit the example above. Without the Google Maps API, developers at OpenTable would have to dedicate their time and resources to drawing their own maps.
Worse still, no matter how much time they put in, it would be nearly impossible to make it as detailed or reliable as Google’s existing solution. Instead of wasting time reinventing the wheel, APIs enable developers to focus on creating new tools that deliver more value.
Increased Productivity
As I mentioned above, using an API from an external provider can save developers time. Internally, APIs offer the same benefit. By creating an internal API, teams don’t need to re-code the same apps over and over again. Beyond that, internal APIs enable businesses to streamline operations, foster collaboration, and strengthen transparency across the company.
Amazon founder Jeff Bezos understood the vast potential of internal APIs. In 2002, he sent an email instructing every team to communicate through APIs moving forward. Following what has been coined “The Bezos Mandate,” developers built or turned their well-developed software components into APIs. This established well-managed ways of exchanging data across the company.
Benefits to API Providers
Now, let’s focus on why you might want to create and then share one with partners or the general public. Simply put, becoming an API provider unlocks business opportunities. Here’s how.
Revenue
, , and thousands of other companies make their APIs available to the public — for a price. They monetize APIs so that they become additional lines of revenue.
In fact, at some companies, APIs are the major source of revenue. According to a recent , 35% of today’s technology leaders generated more than a quarter of their organizations’ revenue as a direct result of APIs.
Scale
Sharing what you do well with the broadest possible audience helps you scale. A network of users — including third-party developers and consumers — will become reliant on your API's functionality.
Ultimately, this will improve the usage and adoption of your main platform. In other words, APIs expand your customer base and generate new market opportunities in the digital economy.
(AWS) is among the most notable examples. This platform allows any company or developer to run its applications on top of Amazon’s infrastructure via APIs.AWS is used by millions of customers. It's credited with .
Even More Innovation
Yes, I’m listing this again, but with a twist. Above, I discussed how API consumers can use these tools to save time. More often than not, however, the relationship between API consumers and providers is much more give-and-take.
You may recall that Twitter’s user interface was a little clunky in the early days (long before the X rebrand). , an independent app at the time, built a better user interface on top of the Twitter platform using its public API.
Twitter later acquired this dashboard so that all users could have better experiences. That’s called a win-win-win, my friends.
How do APIs work?
APIs are sets of definitions and protocols that allow software components to talk and interact with each other using a simple set of commands. Acting as messengers, APIs deliver one application’s request to another and return a response in real time.
If the server (the application providing the resource) can do what the client (the requesting application) asked, then the API returns the resource needed and a status code that indicates “mission accomplished.”
But, sometimes the server can’t do what the client asks. Maybe the client requested a resource that doesn’t exist or that it doesn’t have permission to access. In this scenario, the API returns an error status code.
Controlling access to the server in this way is crucial. Rather than give you all of a program’s information or code, an API provides you only with data made available to external users.
Components of an API
There are multiple building blocks that need to be put together for an API to work. These building blocks are known as components. Below, I’ll discuss what each component does and how they work together to implement APIs.
API Client
API client allows you to send data to and receive data from another system. I don’t need to reinvent the wheel and write the same code again and again in order to make an API request. Instead, I can tell the API client to make a request on my behalf by feeding it the required information.
An API client can be different things — it can be a utility in the browser, or it can be an SDK (software development kit), but, in essence, it’s a way to interact with the API.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
You're all set!
Click this link to access this resource at any time.
API Request
An API request allows you to ask for a resource from a server. The request itself has several components. Below I’ll cover the components of a REST API request.
Method
There are five common API request methods — GET, POST, PUT, PATCH, and DELETE. Each defines an operation you want to perform on the requested resource. Each request method has its own way of sending data. They are a part of the HTTP protocol, which is used to send data between systems in REST APIs.
I’ll discuss these methods in more detail below.
Endpoint
An endpoint is a specific URL or location where data or resources needed by the API are hosted. It acts as a gateway where one software system can send requests to and receive responses from another. Each endpoint performs a distinct function — such as retrieving data, updating records, or processing information.
Headers
Headers contain metadata about the request — the information for the system (server) to understand the request coming in, how to parse it, who requested it, and so on. They are defined as key-value pairs, with each key-value pair representing some information about the request.
Headers also include authorization tokens, which allow the server to authorize a request and verify that it’s coming from an authorized entity.
Parameters
Request parameters are additional information that can be passed to the server. They are variables that generate different responses.
For example, if I want to get information about a particular user in a system, I can pass in a user ID in the request parameters, and the server will send me the data about that particular user. GET method appends the parameters in the URL. Note that many browsers and servers limit URL length (often around 2048 characters), so it’s best to use POST if you’re sending a lot of data.
Body
A request body contains the data you want to send to the server to create, update, or delete a resource. The GET method doesn’t require a request body, as it’s only used for fetching a particular resource from the server. You can define the format of the data embedded in the body using the Content-Type header.
API Server
As the name suggests, an API server handles incoming API requests. The server has certain defined endpoints and serves the request based on what those endpoints return. One server may talk to other servers or systems to fetch the information requested in the request.
API Response
An API response is a response that the server sends to the client for a particular request. The response depends on a lot of factors, including parameters, headers, and body. API responses can vary from system to system, but they generally include the following.
Status Code
An HTTP code that ties to a response outcome. The most common codes include:
- 400 — “Bad Request,” meaning the server cannot process the client’s request because of an error, like invalid data or malformed syntax.
- 404 — “Not Found,” meaning the server cannot find the resource.
- 403 — “Forbidden,” meaning the client does not have permission to access the resource.
Here’s a complete list of .
Headers
These headers are response headers and are different from the request headers. They are sent by the server to the client and contain information about the response, such as the type and length of the content.
For example, the Cache-Control response header provides caching information to the client. Another example of a response header is the Access-Control-Allow-Origin, which defines which origins can access the contents of the server.
Body
Just like the request body, the response body contains the response data. If there’s an error, you can catch it and send it to the client in the response body, along with the appropriate status code.
API Calls
An API call is the process of a client application submitting a request to a server's API. An API call also comprises everything that happens after the request is submitted. This includes when the API retrieves information from the server and delivers it back to the client.
Request Methods
Most clients want the server to carry out basic functions. These requests may be written as URLs. In this case, the communication between the client and server is dictated by rules. The four most common request methods to a server are:
- GET: To retrieve a resource.
- POST: To create a new resource.
- PUT: To edit or update an existing resource.
- DELETE: To delete a resource.
Still confused? Let’s try an analogy. How APIs work is often compared to ordering food at a restaurant. Here, the diner represents the client. The waiter represents the API, and the chef represents the server.
I look over the menu, pick the meal I want, and place my order with the waiter. The waiter brings my request to the chef. The chef executes it. Then, the waiter brings me my meal. I enjoy it, and I didn’t have to cook myself.
But let’s say too many guests show up at the restaurant, and there’s not enough space to accommodate them. Let’s say this keeps happening as the restaurant grows in popularity. What then? That’s where API authorization comes into play.
What is API authorization?
API authorization determines what actions a client can perform once they are authenticated by the API. Authentication comes before authorization. This is where the client's identity is confirmed via an API key, authentication tokens, or other credentials.
Back to our restaurant example: Authentication is like a code to get into a speakeasy. Once the security team hears the secret words, it knows I can be trusted.
After the identity is confirmed by the API, it checks its permissions and determines if the request should be allowed. This is API authorization, and it's critical to security.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
You're all set!
Click this link to access this resource at any time.
What is an API key?
An API key is a unique identifier used to authenticate calls to an API. The key is made up of a string of letters and numbers that identify the client. (Remember, this is the application or site making the request.)
The key can grant or deny that request based on the client’s access permissions. The key also tracks the number of requests made for usage and billing purposes.
API keys are less secure than authentication tokens. However, this method has advantages over basic authentication, which only requires a username and password. By restricting access only to those with keys, a company can control the availability of its data. This ensures that only a specific, trusted group of clients can access its server’s resources.
Continuing my example above, think of an API key as a reservation and the API as an exclusive restaurant. By enforcing that patrons must have a reservation to eat at the restaurant, the business can maintain capacity. The kitchen can adequately and efficiently serve every guest.
Similarly, by allowing only clients with an API key to access and use your resources, you help ensure your software is used safely. You can also guarantee that you can handle the number of incoming requests.
What are APIs used for?
A better question might be, what are APIs not used for? Want to embed Instagram photos on your ecommerce app? There’s an for that. Want to provide instant access to thousands of hotels on your travel blog? There’s an for that.
Generally speaking, business applications of APIs include:
- Data sharing. Any time a program needs to get data from a third party (e.g., a travel app compiling flight times from airlines), data can be shared through an API.
- App integrations. When two digital applications work in conjunction — 51吃瓜 and Gmail, for example — an API is likely involved.
- Embedded content. To embed a piece of content that is hosted on a different website — like a YouTube video — a request is made to the embedded content's owner to retrieve it.
- Internal systems. APIs aren't only for sharing data externally. Businesses frequently divide their software infrastructure into smaller components. These elements communicate with each other through APIs, like in a microservice architecture.
These examples hit upon some of the most common reasons companies use APIs. Below, I’ll explore the types of APIs you should know.
Types of APIs
APIs can be categorized by their intended audience and scope. There are four main types of APIs that developers work with:
- Private APIs. These APIs are only made available to a company's internal team to boost productivity and transparency. Developers working for the company can use these APIs as needed. Third-party developers can’t.
- Partner APIs. These APIs are shared externally but only with those with a business relationship with the API company. Some businesses use partner APIs because they want control over who can access their resources and how they get used.
- Open APIs. Open APIs, or public APIs, are available for external use. While some open APIs are free, others require a subscription fee, which is often tiered based on usage.
Composite APIs
Composite APIs allow you to bundle calls or requests to get one unified response from different servers. You would use a composite API if you need data from different applications. Or, instead of making five separate API calls in succession, you can make one using a composite API.
Composite APIs get their own category because they can be combined with the APIs listed above. For example, you can have a composite private API or a composite open API.
REST APIs
REST is shorthand for a software architectural style called “Representational State Transfer.” It determines how the API should work and makes it easier to use and discover on complex networks like the Internet.
With REST APIs, everything is treated as a resource. This includes data, services, and objects. Each resource is identified by a uniform resource identifier, or URI. Often, the URI will be a URL, since REST APIs most commonly use HTTP or HTTPS in their schemes.
In many REST APIs, resources follow the naming convention:
- Plural or collection: This represents a collection or group of resources.
- Singular: This respresents a single resource.
For example, if I wanted to retrieve a list of all users from a server, I might use a plural pattern called "/users." But, if I wanted to get information on one specific user, I would add an additional identifier to the URL like this: /users/{id}. Now, I am narrowing our focus down to one specific user.
These are also referred to as endpoints. Each endpoint is also assigned a list of actions the client can request from the server. So, a plural endpoint may be for listing or creating resources. The singular endpoint may be for retrieving, updating, and canceling a specific resource.
The client would have to include the correct HTTP verb (GET, POST, PUT, DELETE) in its request to tell the server what action to take. Here are a few examples:
- GET /records: Retrieves a list of records.
- POST /records: Creates a new record.
- PUT /records/123: Updates the record with the ID of 123.
- DELETE /records/123: Deletes the record with the ID of 123.
Here are a few data formats that the client and server can use to pass this information back and forth:
- (Extensible Markup Language).
- (JavaScript Object Notation).
- HTML (Hypertext Markup Language) — though this is not as commonly used.
REST API Example
that enables developers to create, read, and update WordPress content remotely. The API does so by carrying JSON objects back and forth between clients and servers.
In other words, by allowing developers to structure how they get data from a server easily, they can spend less time accessing said data. They can now focus on better user experiences.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
You're all set!
Click this link to access this resource at any time.
REST vs. SOAP
REST is usually put head-to-head with Simple Object Access Protocol (SOAP), another way to build applications that work over HTTP.
REST is to SOAP, as it requires writing less code to complete tasks. REST APIs also follow a less rigid structure and logic than SOAP. Another reason people love REST: it provides plenty of conventions but leaves many decisions up to the person designing the API.
Due to its simplicity and flexibility, most developers (including ours at 51吃瓜) will opt for a REST architecture in their APIs.
How to Use an API
So, you’re ready to try your luck with APIs. Now what? Before implementing your own API at your company, it makes the most sense to use others’ APIs. Let’s discuss the basics of getting started.
1. Select an API.
First, I want to find an API to incorporate into my business. I might already have my eye on an API, particularly if I’m interested in one of the big wigs like the Facebook API. I might also want to search by cost. I often start with a free API before exploring paid APIs.
Once I have an API selected, I get my reading glasses. It’s time to look through the API documentation.
2. Choose your authorization method.
As mentioned earlier, I have a few options when it comes to API authorization:
- API key.
- Authentication tokens.
- User credentials.
In this example, I’ll use an API key.
An API key identifies me as a valid client, sets access permissions, and records my interactions with the API.
Some APIs make their keys freely available, while others require clients to pay for one. Either way, I’ll most likely need to sign up for the service. I’ll then have a unique identifier assigned to me, which I will include in my calls. Keep the following things in mind while using an API key:
- Always keep your key private, like you would a password.
- Don’t push your API keys to a public repository.
- If your key leaks, a bad actor could make API requests on your behalf.
- Revoke your old key and get a new one if such a breach occurs.
3. Review the API documentation.
API Documentation is essentially an instruction manual about how to use an API. In addition to providing documentation, it usually includes examples and tutorials.
Refer to the documentation for:
- How to get your key.
- How to send requests.
- Which resources you can fetch from the server.
- Use cases for different API endpoints.
It’s hard to understate the importance of good API documentation. A company might offer a powerful API, but if developers can’t quickly learn how to use it, it’s not very valuable.
4. Write a request to an endpoint.
Next, I write my first request. The easiest method is to use an HTTP client to help structure and send my requests. I still need to understand the API’s documentation, but I don’t need much coding knowledge to be successful.
I need to make sure the following things are properly specified for you to make your API request:
- Parameters.
- Headers.
- Body.
- Endpoint URLs.
- Request payload.
I can then use a tool like cURL or Postman to send the constructed HTTP request to its endpoint. I can also use a programming language to accomplish this as well.
Here's an example using cURL:
curl -X GET “https://api.example.com/resource” -H “Authorization: Bearer YOUR_ACCESS_TOKEN”
5. Connect your app.
Now, I can sync your application with the API. As a marketer, you don't need to worry about this stage of API integration. This is the job of a developer who will employ languages like Python, Java, JavaScript (and NodeJS), PHP, and more.
How to Connect an App to an API
Connecting or integrating an existing application to an API is quite simple. I’ll work through an example using OpenAI to show you how to integrate and use APIs in an app.
1. Referencing Documentation
As mentioned above, after selecting an API, I check out the official documentation of the API platform I chose and read it carefully. If I’m interested in one of the paid API features, I visit the provider’s pricing page and sign up. Most platforms have their API platform link in the footer of the website.
2. Getting an API key
OpenAI’s API requires an API key to authenticate the request. So, I’ll grab it from the API keys section of their API platform.
I click on the “Create new secret key” button, and it generates a new API key for me. Not only that, but I can also set customized permissions for that API key.
I have seen a lot of people exposing their API keys, but you must not do that. If you lose an API key, revoke/delete the old one and generate a new one.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
You're all set!
Click this link to access this resource at any time.
3. Selecting an API client
Selecting an API client or an SDK depends on your application. OpenAI provides SDKs for two programming languages — and . However, I can also make API requests using cURL, but that’s a terminal-based tool. So, it’s best to search for an SDK that supports the programming language of your choice.
4. Installing Dependencies
I am going to use the Node.js SDK provided by OpenAI. To use it, I need to install the following package in my application:
|
npm install openai |
Then, I can instantiate the SDK as shown below:
|
import OpenAI from “辞辫别苍补颈”; const openaiClient = new OpenAI({ apiKey: "<your_openai_key>" }); |
5. Making your first API request
Now that I have instantiated the SDK, I can use it to make API requests in an idiomatic way (i.e., using methods in node.js instead of using the bare URL endpoint). That’s the benefit of using an SDK, as the API request feels inherently a part of the language.
|
const response = await openAI.chat.completions.create({ model: "<model_name>", messages: [ { role: "system", content: "<your_system_prompt>", }, { role: "user", content: "<your_user_prompt>", }, ], }); const { message } = response.choices[0]; console.log(message); |
The API response will be stored in the response variable, and you can log that to the console, as shown above.
If I were to make an API request in the terminal using cURL, it would look something like this:
|
curl https://api.openai.com/v1/chat/completions \ -H “Content-Type: application/json” \ -H “Authorization: Bearer $OPENAI_API_KEY” \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "this is my first API request"}] }' |
And here’s the response I got:
Integrating an API with an application is as simple as that. Here’s a quick summary of what I did:
- Went to the API platform documentation and referred to it.
- Got an API key for authenticating API requests.
- Searched for an API client or an SDK to make API requests.
- Installed necessary dependencies.
- Made an API request.
API Examples
You’ve probably heard of a few without searching an API marketplace or knowing much about APIs. Below, we’ll look more closely at several examples in action.
51吃瓜’s platform appeals to businesses with three main needs:
- Those looking to build an app and put it in front of thousands of potential users.
- Those looking to create a custom integration between their app and 51吃瓜’s application.
- Those looking to build or extend the functionality of their website.
51吃瓜's APIs can help you gather data from transactional software and store contacts. There are also ways to engage with third-party tools and custom apps in one CRM.
If you work for a brand that loves X, you can use the social media platform’s APIs to drive user engagement on your site.
X has a whole platform offering APIs that allow you to dig through the platform’s massive archive. You can use X APIs to find old Tweets, embed timelines within your website, or manage ad campaigns. Other APIs can do the following:
- Filter and stream Tweets in real time.
- Deliver personalized customer service through direct messages.
- Subscribe to the real-time activities of more than 15 accounts via webhooks.
There are also a ton of available with documentation. This can help you harness the full potential of its global communication network.
Instagram’s platform offers a range of APIs to help your business with content publishing, metrics, and more.
One potential use case is to embed user-generated Instagram photos on your app. User-generated content (UGC) is a strong form of social proof that can entice leads to convert.
Developers plug into this platform to build apps and services that target three groups:
- Individuals looking to share their own content with third-party apps.
- Brands and advertisers needing to understand and manage their audience and media rights.
- Broadcasters wanting to discover content and get digital rights to media or share it with proper attribution.
YouTube APIs enable you to add functionality to your site and access YouTube’s video library.
Let’s walk through a few reasons you might want to use one of YouTube's APIs:
- To play videos directly in your app.
- To let users search content and upload videos.
- To create and manage playlists.
- To gain insight into how users are interacting with your videos and channel
- To schedule live broadcasts.
You’ll need to get a YouTube API key to unlock its potential.
If you’re in the music industry, check out the Spotify Web API. You can now easily add music player functionalities to your website or application.
Using , you can get complete access to the Spotify Data Catalog. This includes albums, musical artists, and tracks. To retrieve user-related data, such as private playlists, users must authorize your app to access their accounts.
The functionalities are nearly identical to what you would find on the native Spotify platform. With the Browse API, for example, your users can access genres, categories, new releases, and playlist recommendations. Spotify also offers Episodes, Follow, Library, and Playlist APIs.
Stuck? Spotify published a list of so you can see how their APIs have been used in the past.
The Google Maps APIs are essential for anyone building a location-based app. For example, if you’re building a real estate app, you can use the Google Maps APIs to include a street view of the property.
The Google platform has an expansive library of APIs with unlimited uses. Want to allow users to request directions? How about including Places on your website? There’s even an API if you’re building a ridesharing app. Google has divided the APIs by usage and platform (web, iOS, or Android), so choose the correct one for your project.
Like most examples, based on monthly usage. The high level of functionality they offer makes them well worth the price.
The PayPal platform has an expansive library of APIs, so you can integrate PayPal functionality into your app. Now, users don‘t need to access PayPal’s website directly. APIs include:
- The Billing Plans API.
- The Catalog Products API.
- The Disputes API.
- Familiar Invoicing, Orders, and Payments APIs.
If you’re building an e-commerce website or running a membership-based organization, the PayPal APIs will help you manage every step of your transactions.
Should you ever feel stuck, PayPal has a strong Here, you can access frequently asked questions and get help from developers working on PayPal integration projects.
There is a vast wealth of APIs available today. To fully appreciate their potential in the digital economy, let’s take a closer look at how APIs are classified by who they are shared with and why.
The Future of the Digital Economy
There are many business advantages to both consuming and providing an API, but let’s keep it simple. Why do APIs matter? They connect your application to the rest of the software world. These connections can empower all types of organizations to create new business models that spur more innovation.
In this way, APIs change how companies do business and shift the way companies think about business.
Editor’s note: This post was originally published in October 2019 and has been updated for comprehensiveness.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
You're all set!
Click this link to access this resource at any time.
![What is Payload? A Quick Guide [+ Examples]](https://www.hubspot.com/hubfs/payload.webp)
