What is an API? How APIs work, simply explained

An Application Programming Interface, commonly shortened to API, is a set of rules which determines how one software program can access the data or functionality provided by another software program.

APIs are an essential part of modern software development. They allow different systems and applications to communicate with each other and share functionality in a flexible and 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

APIs often come in the form of a library that a software developer can include in their code. This library provides a set of functions that can be called upon to perform various tasks. The API specifies the function calls, the inputs they accept, and the outputs they return.

Here's a simplified overview of how APIs work:

• A client sends a request to the API server, usually over the internet or a local network. The request is made using a specific protocol (such as HTTP) and includes information about the operation the client wants to perform, e.g., retrieving data or updating a resource.
• The API server receives the request and processes it. It may validate the request, authenticate the client, authorize the request, or perform 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 from both your location and other places around the world.

To do this, you'll need a way to get the coordinates (latitude and longitude) of the your location or chosen destination, than match it against the weather forecast. You could manually enter this information as and when the user requests it, but that would be extremely time-consuming and prone to error.

Instead, you could use an API provided by a company that maintains a database of meteorological data. You could use this API to search for the weather forecast in your city and deliver the information in a matter of seconds.

In such a project, using an API would save you a lot of time and effort. As well, it would ensure that data is accurate and up to date. The API would access and query the database, while your app would simply display the information returned by the API.

Like the example above, you can use APIs in a multitude of scenarios to access a wide variety of data and functionality. You could use them to retrieve the latest news headlines, look up restaurants in your area, or look up information about a specific product.

Using an API typically involves the following steps:

An API call is a request made to an API to access data or functionality. A client makes an API call and sends a request to the API server, and the server sends back a response. The request and response use a specific format and structure, and are transmitted using a specific protocol (such as HTTP).

To make an API call, you should have access to the API documentation. This documentation provides information on the API's capabilities, the structure of the requests and responses, and any authentication or authorization requirements. You may also need to obtain an API key or other credentials before you can make API calls.

An API key is a unique identifier used to authenticate API requests. API keys will typically track and control how you can use an API. They can also provide access to an API's data and functionality.

API keys guide the correct operation of an API as per the terms of use. They can limit the number of API requests that a client can make, for example. An API key can also track the usage of an API, or make sure that the data provided by an API is being used appropriately.

API keys are usually provided by the API provider and are required to make API requests. They can be generated and managed through the API provider's developer portal, and are often specific to a particular API or application.

API keys are typically present in the header of an API request, and are used to authenticate the request. Other authentication and authorization credentials, such as an OAuth token or a JSON Web Token (JWT), may also be used in tandem.

An API endpoint is a specific location on a server which can receive and respond to API requests. An API endpoint is identified by a URI (Uniform Resource Identifier) and is typically associated with a particular API or service.

APIs and webhooks are both ways that different software components can communicate with each other over the internet. However, they differ regarding how they work and when they are used.

As explained above, APIs are a set of rules and protocols that define how different software components can interact with each other. They provide a way for different systems and applications to communicate with each other, share data and functionality, and work together to perform tasks. To use an API, a client sends a request to the API server using a specific protocol (like HTTP) and gets a response. The client and server communicate through a series of requests and responses, and the API defines the specific format and structure of these messages.

How are APIs different from webhooks? Webhooks are a way for a server to send data to a client in real-time, without the client needing to make a request. When a specified event occurs on the server, the server can send a message to a specified URL. The message is usually in the form of an HTTP POST request. The client can then process the message and act based on the data received. Webhooks are often used to 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 they apply to different situations and for different purposes. To learn more about the differences, see our post comparing Webhooks vs APIs.

APIs are extremely useful for situations where communication and interoperability between different systems and applications is needed. Here's a few examples of common applications for APIs:

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. Alternatively, it would 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 might use an API to retrieve a user's feed, or to publish a new post.

Internet of Things (IoT)

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

Third-party services

APIs allow different applications and services to work together and share data. For example, a customer relationship management (CRM) system might use an API to integrate with a marketing automation platform. Or a project management tool might 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. With distinct parts, different services can be developed, tested, and deployed independently, which makes it easier to scale and maintain the overall application.

There are many different types of APIs. Some common categories include:

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

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. A well-designed API architecture should be flexible, scalable, and easy to use, with clear documentation and a robust support system for developers. There are several types of API architectures in widespread use. Here's an overview of the most common:

Representational State Transfer (REST) APIs

REST APIs are a type of web API that uses HTTP requests to manipulate data. They're designed to be lightweight and flexible, and 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 (Uniform Resource Identifier). Examples of these verbs are GET, POST, PUT, and DELETE. REST APIs are also useful for creating 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, for building web services that are interoperable between different programming languages and platforms. SOAP APIs use 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

GraphQL is a query language and runtime developed by Facebook as an alternative to REST and SOAP APIs.

GraphQL creates a representation of your data that is designed to feel familiar and natural, like a visual graph. The graph part of GraphQL describes a data structure of a collection of objects — or nodes — that are connected to each other through a set of links, or edges. Relationships between different objects can be represented in a user interface as a result of this graph structure. The key concept is that the data structure is non-linear, meaning that one object can be connected to more than one other object, and relationships can also be circular.

So what are the benefits here? Using GraphQL, clients can request only the data they need rather than receiving a fixed set of data from a server. It's flexible and efficient, while also being easy to use and learn, with a simple syntax and powerful tools for building and testing queries.

A web API is an API that's accessed over the internet using HTTP (Hypertext Transfer Protocol). Web APIs allow different systems and applications to communicate with each other over the internet. Web applications built with web APIs are accessible from any device with an internet connection.

You might 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.

It may surprise you to learn that application programming interfaces predate the existence of the World Wide Web. As far back as the 1940s, in fact, with the emergence of the first computers.

British computer scientists Marice Wilkes and David Wheeler were working on a software library for the Electronic Delay Storage Automatic Calculator (EDSAC). The pair programed EDSAC to accept a variety of instructions like add, subtract, print, load, and store. This behavior is similar to how modern web APIs interface with data today, for example, "add blog post," "delete blog post," or "get blog post information."

Wilkes and Wheeler documented the uses of EDSAC via a catalog of notes about its functionality and how to integrate it with other programs. It was the first example of the type of API documentation we know today.

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

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

These are a few examples. There are many other companies and organizations that create APIs for a wide variety of purposes, including social media, finance, healthcare, and education.

An API-first CMS (Content Management System) is a type of CMS that exposes its content and functionality through APIs. They provide a robust and flexible set of APIs to build a range of applications and integrations.

An API-first CMS is flexible and modular by design. They leverage 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 CMSs 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.

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 to access and manipulate content stored in Contentful.

Here's an overview of the steps you can follow to use Contentful's APIs:

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

• Content Delivery API
• Content Management API
• Preview API
• Images API
• GraphQL Content API