API stands for application programming interface. An API is basically a set of definitions and protocols that enable two applications to talk to one another. APIs are the connectors that enable most of the communications between the web applications, or apps, that we use today. For example, if you use apps on your phone to check the weather, or send a message to friends, or to find the nearest cafe, you’ll be using APIs without even knowing it.
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.
APIs work by communicating with, and exchanging data between, other systems. They act as the messengers between us, the users, and the backend systems, allowing us to retrieve the data we want, when we want it. Let’s take a familiar example. Say you’re going to stay at a hotel, but you’ve not been there before, so you want to use a navigation app to get there. You input some details about the journey into the app, like the destination address, whether you’re going by car or by public transport, and any route preferences. Now, for the app to provide you with a complete navigation picture, it will check several different services, such as GPS data, weather information, public transport timetables, route delays, amenities, and so on. The navigation app will interact with all of these services by using APIs.
In software terms, APIs are a set of functions and procedures that allow application developers to create apps that use the data and features of other services and applications. APIs give developers a toolset that they can use to create their apps.
There are three main types of APIs:
Open APIs, which are publicly available with minimal restrictions to access them.
Partner APIs, which need specific access rights to be able to use them and are typically exposed via an API developer portal.
Internal APIs, which are hidden from external users and only exposed by internal systems. Typically, these are exposed via an internal API developer portal to enable authorization to the right set of APIs.
There are also two different ways that APIs can be implemented:
Simple APIs, which are available separately.
Composite APIs, where multiple data or service APIs are combined together, allowing developers to access several APIs at a time. For example, you'd implement composite APIs in a microservices architecture, where a user needs information from several endpoints to perform a single task, like the navigation app example we described previously.
To be able to use APIs effectively, developers must adhere to a common set of rules, or protocols, when making API calls. The term API call simply refers to the process of communicating with an API; in other words, an API call is when data is sent to and retrieved from an API endpoint.
There are three main types of API protocols:
REST. REST is short for Representational State Transfer and is a web services API. It provides a uniform interface, where a client and server communicate with one another via Hypertext Transfer Protocol (HTTP), by using Uniform Resource Identifiers (URIs), the common Create, Read, Update, and Delete (CRUD) operations, and most often JavaScript Object Notation (JSON) conventions for data exchange.
SOAP. SOAP is short for Simple Object Access Protocol and is another type of web services API. SOAP APIs have been used since the 1990s, but the protocol is stricter and more heavyweight than REST, so it isn’t used as much in modern API development.
RPC. RPC is short for Remote Procedural Call and is the oldest and simplest type of API protocol. RPC is a request-response protocol, where a client sends a request to a remote server to execute a specific procedure, and then the client receives a response back. However, RPC APIs are much more difficult to maintain and update than REST APIs, so again RPC APIs aren’t used as much in modern API development.
REST APIs have become the preferred standard for building apps that communicate over a network. However, there is a new data query and manipulation language for APIs that is rapidly gaining ground called GraphQL. GraphQL provides a different approach to API development, where the client, or app developer, has much greater control over what data is returned.
Which is better, REST or GraphQL? Watch this video to see.
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:
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.
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.
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 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.
These days there are many different technologies that you can use for developing APIs, such as REST, OpenAPI, HTTP, gRPC, GraphQL, and Kafka. Which technology you choose really depends on what style of API that you want to develop and your overall business strategy and constraints.
Here are the five main styles of API development:
Tunnel. In this style, the API is a collection of functions that can be called remotely. A common technology used in this style is Remote Procedure Call method. The tunnel style is focused on making specific computer functions available. This is a popular style; for example, gRPC is an open source remote procedure call framework you can use to develop APIs.
Resource. In this style, the API is a collection of resources that can be interacted with. This style is likely the most popular style for public APIs, enabling resources like products, customers, and other data to be accessed. A common technology that’s used for this API style is HTTP that calls an API that’s been written following the OpenAPI specification. (The OpenAPI specification defines a standard, language-agnostic interface to RESTful APIs.)
Hypermedia. This style is an enhancement of the Resource style. In this style, the API is a collection of interlinked resources, which is very much how web apps are delivered. Similarly, this style often uses HTTP calls to an OpenAPI-described service, with the difference being that the data also includes controls to link the resources together.
Query. In this style, the API exposes a structured data model that can be queried and updated by using a generic query language. This style is usually used when you have a large amount of data, where the API needs to query the dataset and return just the data needed for that query. A very popular example of a technology that uses this style is GraphQL, as noted previously. GraphQL is a very flexible query language that allows you to ask for specific sections of a large data model, thereby enabling API developers to interrogate large amounts of data much more efficiently.
Learn more about what is Apache Kafka in this article.
Once you’ve chosen your development style, then you can look for the technology that’s the best fit. There's no 'one size fits all' in API development. You should make a considered design choice that fits your business, and invariably that technology will evolve over time.
Now, let's look at why businesses use APIs. Although there are many varied reasons to develop APIs, here are our top four:
Speed. Having a library of reusable APIs speeds up application development and ongoing app evolution.
Security. APIs enable you to securely expose systems of record and business logic to mobile, web, and cloud apps.
Socialize. Publishing APIs expands your brand reach and enables you to tap into broader developer and partner ecosystems to drive innovation.
Monetize. Enable new business channels by charging money for the use of, or rate of use of, the APIs that can access your data and algorithms.
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:
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.
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.
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.
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.
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:
| 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 the 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 who have a business relationship with the organization that created the API. Usually this group consists of partners or third-party developers. |
| 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 category depending on how it's used.
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:
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.
Using an API typically involves the following steps:
| Step | Description |
|---|---|
| 1. Find an API | The first step in using an API is to 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, the next step is to 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, it's important to understand its terms of use. These terms will specify limitations on how you can use the API, and how you can use and share the API's data. It 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 it. The API key is a unique identifier used to authenticate your API requests. You're given one after you sign up for the API 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. The API request usually contains a URI that identifies the resource you want to access. It'll also have an HTTP verb (such as GET or POST) to specify the operation you want to perform. 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 | Cache data to reduce the number of API requests, handle errors and exceptions gracefully, and respect the API's terms of use. By following best practices like these, you'll make sure that your use of the API is efficient, reliable and compliant. |
In this article, we covered the basics of API development, discussing API protocols and styles of API development. We also covered the key benefits of developing APIs.
In the modern world, APIs have become a valuable business asset in themselves. This is what's commonly referred to as "the API economy."