The API guide

What is an API? How APIs work, simply explained

David Fateh

Updated: January 15, 2025

The API guide

In this guide, you'll find everything you need to understand the fundamentals of APIs, how they enable seamless integration between systems, and why they are essential for modern digital experiences.

We’ll explore topics like how APIs work, what API endpoints and keys are, how API calls function, and the role of headless APIs in powering flexible, scalable solutions. By the end, you’ll have a solid foundation to leverage APIs effectively in your projects.

What is an API?

An application programming interface, typically shortened to API, is a set of rules which determines how one software program is able to access the data or functionality provided by another software program.

Use of APIs dates back to the 1940s, when British computer scientists Maurice Wilkes and David Wheeler were programming the Electronic Delay Storage Automatic Calculator (EDSAC) to accept instructions like ’add,” “subtract,” “print,” “load,” and “store.” This programmed behavior is similar to how modern web APIs interface with data — for example, “add blog post,” “delete blog post,” or “get blog post information.”

Today, APIs are an essential part of software development. They allow different systems and applications to communicate, exchange data, and share functionality in a flexible, efficient way.

They’re used in a wide variety of contexts, including web development, mobile apps, and Internet of Things (IoT) applications.

Read on below

Dive deeper into APIs

How do APIs work?

APIs enable applications to exchange data as part of a request and response process. They typically come in the form of a library that a software developer can include in their application’s code. This library contains a set of functions that facilitate various tasks between one application and another. The API specifies the function calls, the inputs that the applications accept, and the outputs that they return.

Here’s a simplified overview of the process:

A client sends a request or call to an API server, usually over the internet or a local network. The request is made using a specific protocol, such as hypertext transfer protocol (HTTP), and includes information about the operation that the client wants to perform, e.g., retrieving data or updating a resource.
The API server receives and processes the request. That process may involve validating the request, authorizing the request, authenticating the client, or performing other necessary operations.
The API server sends a response back to the client, which may include data, an error message, or a status code indicating the result of the operation.
The client receives the response and processes it.

Let’s go deeper with a real-world example. Imagine you’re building an app that displays the weather in your location and in other locations around the world. For your app to work, you’ll need a way to get the coordinates (latitude and longitude) of your location or of a chosen destination, and then match that information against the relevant weather forecast.

You could do that by manually entering the information when a user requests it — but that’s likely a time-consuming and error-prone process. As an alternative, you could use an API provided by a company that maintains a database of meteorological data to search for the relevant forecast, and deliver the requested information to the user. The API would access and query the database, and then your app would simply display the information that it returned in a matter of seconds.

For this kind of project, using an API saves a lot of time and effort, while also ensuring that the data is accurate and up to date. Beyond the possibilities for weather apps, you can use APIs in a multitude of scenarios to access a wide variety of data and functionality, including retrieving the latest news headlines, looking up local restaurants, or finding information about a specific product.

Using an API: Step by step

Here’s a step-by-step guide to finding and using an API:

Step	Description
1. Find an API	Find an API that provides the functionality you need. There are many APIs available on the internet, and you can search for APIs using search engines, developer portals, or API marketplaces.
2. Read the documentation	Once you have found an API that you want to use, read the API documentation. The documentation should provide information on the API’s capabilities, the structure of the requests and responses, and any authentication or authorization requirements.
3. Understand the API's terms of use	Before you begin using an API, make sure you understand its terms of use. The terms typically specify limitations on how you can use the API, and how you can use and share the API’s data. They may also explain whether the API is free or requires a paid subscription.
4. Obtain an API key	Many APIs require you to obtain an API key before you can start using them. API keys are usually obtained via the API provider. They can be generated and managed through the API provider’s developer portal, and are often specific to a particular API or application. You’ll typically receive your key after you sign up or after you agree to the API’s terms of use.
5. Make API requests	Once you have an API key and have read the API documentation, you can start making API requests — also known as API calls. You can make API requests using a tool such as a command-line utility, or a library in your programming language of choice.
6. Process the API response	When you make an API request, the API server will send a response back to you. The response may include data, an error message, or a status code indicating the result of the operation. It’s important to process the API response and handle any errors or exceptions that may occur.
7. Follow best practices	Learn and apply the API’s best practices, such as caching data to reduce the number of API requests, handling errors and exceptions gracefully, and respecting the API’s terms of use. By following best practices like these, you’ll ensure that your use of the API is efficient, reliable, and compliant.

How are APIs different from webhooks?

APIs and webhooks both enable different software components to communicate with each other over the internet, and both facilitate transfers of data. However, they differ in terms of functionality and the contexts in which they are normally used.

APIs represent a communication layer between applications that facilitates an ongoing series of requests and responses. One app sends a request for data, another responds by sending that data, and the API defines the specific format and structure of that two-way, data-transfer conversation.

While webhooks also send data between applications, that transfer isn’t initiated by a request, but when a specific predefined event takes place. When the predefined event occurs, the server sends a message to a specified URL, usually in the form of an HTTP POST request. The client application processes the message and acts based on the data received. Webhooks enable real-time communication and event-driven architectures, and can be used to build more efficient and responsive systems.

Both APIs and webhooks are incredibly useful tools for building interconnected systems, but are not interchangeable. To learn more about the differences, see our post comparing webhooks vs. APIs.

Common API applications

APIs are extremely useful in situations where communication and interoperability between different systems and applications is needed. Here are a few examples:

Web development

APIs are a core component of web-based applications which are accessible from any device with an internet connection. For example, an API would allow an app in your web browser to communicate with a server-side application or, alternatively, enable a web-based application to retrieve data from a database.

Mobile apps

You can use APIs to build dedicated mobile apps that can access data and functionality from a server-side application or cloud service. For example, a social media app on your smartphone will use an API to retrieve a user’s feed or to publish a new post.

Internet of Things

APIs also enable communication between IoT devices and other systems and applications. For example, an API can facilitate communication between a smart thermostat and a home automation system, or enable an IoT device to send data to a cloud service for analysis.

Third-party services

APIs allow different applications and web services to work together and share data. For example, a customer relationship management (CRM) system would use an API to integrate with a marketing automation platform, or a project management tool would use an API to integrate with a time-tracking application.

Microservices

APIs are extremely popular for building microservices architectures. A microservice is the result of breaking down a large application into smaller, independent services that communicate with each other through APIs. As distinct parts of a larger entity, the different services can be developed, tested, and deployed independently, which makes it easier to scale and maintain the overall application.

Types of APIs

Although there are many different types of API, some common categories include:

Type	Description
Open APIs	These are made available to developers outside the organization that created them. Open APIs provide access to a specific product or service, and are available to anyone who agrees to their terms of use. They are also known as external or public APIs.
Internal APIs	These are used within an organization to share resources and functionality between different teams or systems. They aren’t usually available to developers outside the organization.
Partner APIs	These APIs are available to a specific group of developers, usually partners or third-party developers, who have a business relationship with the organization that created the API. Users may need to complete an onboarding process to gain access to partner APIs.
Composite APIs	These are APIs that combine multiple underlying APIs into a single interface. They provide a simplified way for developers to access multiple resources or functionality in a single call.

It’s worth noting that these categories aren’t mutually exclusive, and an API may fall into more than one depending on how it’s used.

API architectures and programming languages

An API architecture refers to the overall design and structure of an API, including the way it’s organized, the types of requests it supports, the data formats and protocols it uses, and any security or authentication mechanisms it employs. Well-designed API architecture is flexible, scalable, and easy to use, with clear documentation and a robust support system for developers.

Some of the most common API architectures include:

Representational State Transfer (REST) APIs

REST APIs are a type of web API that uses HTTP requests to manipulate data. Designed to be lightweight and flexible, REST APIs are great for building web services that are scalable and easy to maintain. REST APIs use a fixed set of HTTP verbs to perform operations on resources that are identified using a URI. Examples of these verbs are GET, POST, PUT, and DELETE. REST APIs are also useful for CRUD (Create, Read, Update, Delete) applications.

Simple Object Access Protocol (SOAP) APIs

SOAP APIs are a type of web API that uses XML (Extensible Markup Language) to encode messages. They’re designed to be extensible and neutral, and are useful for building web services that are interoperable between different programming languages and platforms. A SOAP API uses a standardized messaging format and transport protocol (usually HTTP) to send and receive messages.

Remote Procedure Call (RPC) APIs

RPC APIs are a type of API designed to make it easy to invoke methods on remote objects, which is useful for building distributed systems. RPC APIs are based on a client-server model. The client sends a request to the server to execute a specific procedure or function, and the server returns the result to the client.

GraphQL APIs

Developed by Facebook as an alternative to REST APIs and SOAP APIs, GraphQL is a query language and runtime that creates a representation of data that is designed to feel familiar and natural, like a visual graph. The graph describes a data structure of a collection of objects — or nodes — that are connected to each other through a set of links, or edges. This visual approach makes it possible to display relationships between different objects in a user interface and, because the data structure is non-linear, one object can be connected to more than one other object, and relationships can be circular.

GraphQL makes it possible for clients to request only the data they need, rather than receiving a fixed set of data from a server. The language is flexible and efficient while also being easy to use and learn, with a simple syntax and powerful tools for building and testing queries.

Web APIs

A web API is an API that’s accessed over the internet using HTTP. Web applications built with web APIs are accessible from any device with an internet connection.

It’s easy to assume that all APIs are web APIs, but this isn’t the case. Some APIs function only within the confines of a computer operating system, allowing local programs and routines to interact with one another.

Who creates APIs?

APIs can be created by any group or individual, including software companies, government agencies, non-profit organizations, and open-source projects. Well-known companies that create APIs include:

Google: Google is a multinational technology company that creates APIs for cloud computing, maps, search, machine learning applications, and more.
Amazon: Amazon is a global ecommerce company that provides a variety of APIs for uses including ecommerce, fulfillment, and payment processing.
Microsoft: Microsoft is a technology company that creates APIs for purposes such as cloud computing, productivity, and machine learning.
Contentful: Contentful is a company that provides a composable content platform with an API-first content management system (CMS) at its heart. The platform includes tools and features to create, manage, and deliver content.

Many other companies and organizations create APIs, for a spectrum of purposes, including social media, finance, healthcare, and education.

What is an API-first CMS?

An API-first CMS is a type of CMS that exposes its content and functionality through APIs. These types of CMS platforms provide a robust and flexible set of APIs to build a range of applications and integrations.

Modular by design, an API-first CMS leverages a microservices-based architecture that allows different components of the CMS to be developed, tested, and deployed independently. It’s also typically designed to be scalable and resilient, with the ability to handle large amounts of traffic and data without performance degradation.

API-first CMSes are often used to build modern web and mobile applications that require flexible and scalable content management capabilities. They can also build integrations with other systems and applications, or enable real-time communication and event-driven architectures.

How do I use Contentful APIs?

Contentful provides a set of APIs to build and manage content-driven applications and websites.

To use Contentful’s APIs, you’ll need to sign up for a Contentful account and create an API key. You can then use the API key to make API requests in order to access and manipulate content stored in Contentful.

Here’s a step-by-step guide to using Contentful’s APIs:

Step	Description
1. Sign up for a Contentful account	Create a Contentful account and sign up for a free trial or a paid plan depending on your needs.
2. Create an API key	Navigate to the “API Keys” section in your Contentful account settings. Here you can create multiple API keys for different purposes, including for different environments or applications.
3. Read our API documentation	Contentful provides extensive documentation for our APIs, including detailed information on the structure of the requests and responses, and examples of how to use the APIs. Familiarize yourself with the documentation before you start using the APIs.
4. Make API requests	You can use a variety of tools and technologies to make API requests to Contentful’s APIs. Common options include command-line utilities such as cURL, libraries in programming languages such as JavaScript or Python, or web-based APIs such as GraphQL.
5. Process the API response	When you make an API request to Contentful, the API server will send a response back to you. The response may include data, an error message, or a status code indicating the result of the operation. It’s important to process the API response and handle any errors or exceptions that may occur.

To learn more about APIs, integration, or how to use Contentful APIs for creating and managing your content, sign up for a free Contentful account and begin creating your space.

Explore Contentful's API documentation

Up next: What is an API endpoint?

Written by