Published: 09 April 2024
Contributor: Michael Goodwin
An API, or application programming interface, is a set of rules or protocols that enables software applications to communicate with each other to exchange data, features and functionality.
APIs simplify and accelerate application and software development by allowing developers to integrate data, services and capabilities from other applications, instead of developing them from scratch. APIs also give application owners a simple, secure way to make their application data and functions available to departments within their organization. Application owners can also share or market data and functions to business partners or third parties.
APIs allow for the sharing of only the information necessary, keeping other internal system details hidden, which helps with system security. Servers or devices do not have to fully expose data—APIs enable the sharing of small packets of data, relevant to the specific request.
API documentation is like a technical instruction manual that provides details about an API and information for developers on how to work with an API and its services. Well-designed documentation promotes a better API experience for users and generally makes for more successful APIs.
Learn how intelligent automation can make your business operations a competitive advantage.
Register for the guide to operationalize FinOps
It’s useful to think about API communication in terms of a request and response between a client and server. The application submitting the request is the client, and the server provides the response. The API is the bridge establishing the connection between them.
A simple way to understand how APIs work is to look at a common example—third-party payment processing. When a user purchases a product on an e-commerce site, the site might prompt the user to “Pay with PayPal” or another type of third-party system. This function relies on APIs to make the connection.
When the buyer clicks the payment button, an API call is sent to retrieve information. This is the request. This request is processed from an application to the web server through the API’s Uniform Resource Identifier (URI) and includes a request verb, headers, and sometimes, a request body.
After receiving a valid request from the product webpage, the API calls to the external program or web server, in this case, the third-party payment system.
The server sends a response to the API with the requested information.
The API transfers the data to the initial requesting application, in this case, the product website.
While the data transfer differs depending on the web service used, the requests and responses all happen through an API. There is no visibility on the user interface, meaning APIs exchange data within the computer or application, and appear to the user as a seamless connection.
APIs can be categorized by use case, including data APIs, operating system APIs, remote APIs and web APIs.
Used to connect applications and database management systems.
Used to define how apps use operating system services and resources.
Used to define how applications on different devices interact.
Used to enable data and functionality transfer over the internet using HTTP protocol.
Today, most APIs are web APIs. Web APIs are a type of remote API (meaning that the API uses protocols to manipulate external resources) that expose an application's data and functionality over the internet.
The 4 main types of web APIs are:
Open APIs are open-source application programming interfaces you can access with the HTTP protocol. Also known as public APIs, they have defined API endpoints and request and response formats.
Partner APIs connect strategic business partners. Typically, developers access these APIs in self-service mode through a public API developer portal. Still, they need to complete an onboarding process and get login credentials to access partner APIs.
Internal, or private, APIs remain hidden from external users. These private APIs aren't available for users outside of the company. Instead, organizations use them to improve productivity and communication across different internal development teams.
Composite APIs combine multiple data or service APIs. They allow programmers to access several endpoints in a single call. Composite APIs are useful in microservices architecture where running a single task might require information from several sources.
Because APIs allow organizations to open access to their resources while maintaining security and control, they have become a valuable aspect of modern business and personal applications.
Here are some API examples that users often encounter:
A popular API example is the function that enables people to log in to websites by using their Facebook, X, or Google profile login details. This convenient feature allows any website to use an API from one of the more popular services for quick authentication. This capability helps save users the time and hassle of setting up a new profile for every web application or new membership.
These “smart devices” offer added functionality, such as internet-enabled touchscreens and data collection, through APIs. For example, a smart fridge can connect to recipe applications or take and send notes to mobile phones through text message. Internal cameras connect to various applications so that users can see the contents of the refrigerator from anywhere.
Travel booking sites aggregate thousands of flights, showcasing the cheapest options for every date and destination. APIs enable this service by providing application users access to the latest information about availability from hotels and airlines.
This access is available either through a web browser or the travel booking company’s own application. With an autonomous exchange of data and requests, APIs dramatically reduce the time and effort involved in checking for available flights or accommodation.
Navigation apps use core APIs that display static or interactive maps. These apps also use other APIs and features to provide users with directions, speed limits, points of interest, traffic warnings and more. Users communicate with an API when plotting travel routes or tracking items on the move, such as a delivery vehicle.
Social media companies use APIs to allow other entities to share and embed content featured on social media apps to their own sites. For example, the Instagram API enables businesses to embed their Instagram grid on their website and for the grid to update automatically as users add new posts.
APIs are an integral part of the growth in software as a service (SaaS) products. Platforms like CRMs (customer relationship management tools) often include several built-in APIs that let companies integrate with applications they already use, such as messaging, social media and email apps.
This integration drastically reduces time spent switching between applications for sales and marketing tasks. It also helps reduce or prevent data silos that might exist between departments that use different applications.
Traditionally, API referred to an interface connected to an application created with any of the low-level programming languages, such as JavaScript. However, modern APIs vary in their architectures and use of data formats. They are typically built for HTTP, resulting in developer-friendly interfaces that are easily accessible and widely understood by applications written in Java, Ruby, Python and many other languages.
As the use of web APIs has increased, it has led to the development and use of certain protocols, styles, standards and languages. These structures provide users with a set of defined rules, or API specifications, that create accepted data types, commands and syntax. In effect, these API protocols facilitate standardized information exchange.
SOAP is a lightweight XML-based messaging protocol specification that enables endpoints to send and receive data through a range of communication protocols including SMTP (simple mail transfer protocol) and HTTP (hypertext transfer protocol.) SOAP is independent, which allows SOAP APIs to share information between apps or software components running in different environments or written in different languages.
Remote procedure call (RPC) is a protocol that provides the high-level communications paradigm used in the operating system. RPC presumes the existence of a low-level transport protocol, such as transmission control protocol/internet protocol (TCP/IP) or user datagram protocol (UDP), for carrying the message data between communicating programs.
RPC implements a logical client-to-server communications system designed specifically for the support of network applications. The RPC protocol enables users to work with remote procedures as if the procedures were local.1
The XML-RPC protocol relies on a specific XML format to transfer data. XML-RPC is older than SOAP, but simpler, and relatively lightweight in that it uses minimum bandwidth.
Like XML-RPC, JSON-RPC is a remote procedure call, that uses JSON (JavaScript Object Notation) instead of XML. JSON is a lightweight format for data exchange that is simple to parse and uses name/value pairs and ordered lists of values. Because JSON uses universal data structures, it can be used with any programming language.
gRPC is a high-performance, open-source RPC framework initially developed by Google. gRPC uses the network protocol HTTP/2 and Protocol Buffers data format and is commonly used to connect services in a microservices architecture.
WebSocket APIs enable bidirectional communication between client and server. This type of API does not require a new connection to be established for each communication—once the connection is established it allows for continuous exchange. This makes Web Socket APIs ideal for real-time communication.
REST is a set of web API architecture principles. REST APIs—also known as RESTful APIs—are APIs that adhere to certain REST architectural constraints. REST APIs use HTTP requests such as GET, PUT, HEAD and DELETE to interact with resources. REST makes data available as resources, with each resource represented by a unique URI. Clients request a resource by providing its URI.
REST APIs are stateless—they do not save client data between requests. It’s possible to build RESTful APIs with SOAP protocols, but practitioners usually view the two standards as competing specifications.
GraphQL is an open-source query language and server-side runtime that specifies how clients should interact with APIs.2 GraphQL allows users to make API requests with just a few lines, rather than having to access complex endpoints with many parameters. This capability can make it easier to generate and respond to API queries, particularly more complex or specific requests that target multiple resources.
SOAP and REST represent different approaches to API design, describing rules and standards for how an API should interact with other applications. SOAP is a protocol while REST is a set of constraints that constitute an architectural style. Both use HTTP to exchange information.
REST is often considered a simpler alternative to SOAP because it is lightweight, flexible, transparent and relatively easy to use; SOAP requires users to write more code to complete each task than REST requires.
SOAP is more deterministic and robust (due to type checking), and proponents make the case that it is easier to use because of the SOAP support built into many development tools.3 SOAP features built-in compliance, and developers often consider it a more secure protocol, better suited for situations with strict data integrity requirements.
RESTful systems support messaging in different formats, such as plain text, HTML, YAML, XML and JSON, while SOAP only allows XML. Each has their strengths, and the “right choice,” might depend on use case. However, the ability to support multiple formats for storing and exchanging data is one of the reasons REST is a prevailing choice for building public APIs.
GraphQL is a query language and API runtime that Facebook developed internally in 2012 before it became open source in 2015. GraphQL and REST are both stateless, use a client/server model and use HTTP. GraphQL solves for some limitations of REST, for example, providing the ability to more accurately target wanted resources with a single request.
REST APIs follows a fixed structure, and always return a whole data set for a specified object. If the request is more complex, spanning multiple resources, for example, the client must submit separate requests for each resource. These limitations can lead to under or over-fetching issues.
Read more about GraphQL vs. REST here
Neither REST nor GraphQL APIs are inherently superior. They’re different tools that are suited to different tasks.
REST is generally easier to implement and can be a good choice when a straightforward, cacheable communication protocol with stringent access controls is preferred (for public-facing e-commerce sites like Shopify and GitHub, as one example).
GraphQL APIs enable more flexible, efficient data fetching, which can improve system performance and ease-of-use for developers. These features make GraphQL especially useful for building APIs in complex environments with rapidly changing front-end requirements.4
A web service is an internet software component that facilitates data transfers over a network. Because a web service exposes an application’s data and functionality to other applications, in effect, every web service is an API. However, not every API is a web service.
APIs are any software component that serves as an intermediary between two disconnected applications. While web services also connect applications, they require a network to do so. Web services are typically private and only approved users can access them.
Microservices is an architectural style that divides an application into smaller, independent components, often connected by using REST APIs. Building an application as a collection of separate services enables developers to work on one application component independent of the others, and makes applications easier to test, maintain and scale.
Microservices architecture has become more prevalent with the rise of cloud computing and, together with containers and Kubernetes, is foundational to cloud-native application development.
APIs simplify the design and development of new applications and services, and the integration and management of existing ones. They also offer significant benefits to developers and organizations at large.
The average enterprise uses almost 1,200 cloud applications (link resides outside ibm.com), many of which are disconnected. APIs enable integration so that these platforms and apps can seamlessly communicate with one another. Through this integration, companies can automate workflows and improve workplace collaboration. Without APIs, many enterprises would lack connectivity, causing information silos that compromise productivity and performance.
APIs offer flexibility, allowing companies to make connections with new business partners and offer new services to their existing market. This flexibility also enables companies to access new markets that can boost returns and drive digital transformation.
For example, the company Stripe began as an API with just seven lines of code. The company has since worked with many of the biggest enterprises in the world. Stripe has diversified to offer loans and corporate cards, and received a recent valuation of USD 65 billion (link resides outside ibm.com).
Many companies choose to offer APIs for free, at least initially, so that they can build an audience of developers around their brand and forge relationships with potential partners. If the API grants access to valuable digital assets, a business monetizes it by selling access. This practice is referred to as the API economy.
When AccuWeather (link resides outside ibm.com) started its self-service developer portal to sell a wide range of API packages, it took just 10 months to attract 24,000 developers, selling 11,000 API keys. This move helped to build a thriving community in the process.
APIs separate the requesting application from the infrastructure of the responding service and offer layers of security between the two as they communicate. For example, API calls typically require authentication credentials. HTTP headers, cookies or query strings can provide additional security during data exchange. An API gateway can control access to further minimize security threats.
APIs provide added protection within a network. They can also provide another layer of protection for personal users. When a website requests a user’s location (a location API provides this information), the user can decide whether to allow or deny this request.
Many web browsers and desktop and mobile operating systems have built-in permission structures. When an app must access files through an API, operating systems such as iOS, macOS, Windows and Linux use permissions for that access.
Manage your API lifecycle across multiple clouds, boost socialization and optimize monetization efforts across your entire business ecosystem.
Connect, automate and unlock business potential with IBM integration solutions.
Connect applications, data, business processes and services, whether they are hosted on-premises, in a private cloud or within a public cloud environment.
Footnotes
1“Remote Procedure Call,” ibm.com, 3 November 2023
2“What is GraphQL,” Chrystal R. China, ibm.com, 8 December 2023
3“Comparing REST and SOAP,” ibm.com, 5 March 2021
4“GraphQL vs. REST API: What’s the difference?,” Chrystal R. China, ibm.com, 29 March 204