Introduction
How does human communication happen? People can express thoughts, needs, and ideas through language (written and spoken), gestures, or facial expressions, right? At the same time, our interaction with computers, apps, and websites requires user interface (UI) components – a screen with a menu and graphical elements, a keyboard, and a mouse.
Software or its elements, on the other hand, don’t need a graphical user interface to talk to each other. To communicate and exchange data and functionalities, programs use machine-readable interfaces called APIs.
If you ever read tech magazines or blogs, you’ve probably seen the abbreviation API. It sounds solid, but what does it stand for? API stands for Application Programming Interface. This article will explain what APIs are, how they work, and why you should care about them in the first place.
What is an API?
An API is a set of programming code that enables data transmission between one software product and another. It also contains the terms of this data exchange.
APIs are mechanisms that enable two software components to communicate with each other using a set of definitions and protocols. For example, the weather bureau’s software system contains daily weather data. The weather app on your phone “talks” to this system via APIs and shows you daily weather updates on your phone.
API examples
As an internet user, you’ve most likely experienced the convenience API technology enables when browsing a website or using a mobile app. APIs are a crucial behind-the-scenes aspect of user experience (UX). Consider a few familiar examples of APIs and how a website owner or administrator might use them:
The YouTube API allows you to add videos to your website or app, as well as manage your playlists and subscriptions.
The Facebook API for conversions allows you to track page visits and conversions, as well as provide data for ad targeting and reporting.
The Google Maps API allows you to embed static and dynamic maps, as well as street view imagery, on your website.
Any time you land on a site and watch a video, see an ad on Facebook related to a website you recently visited, or use the map on a business’s website to find its physical location, chances are an API has been at work to make this experience possible.
How do APIs work?
The working principle of an API is commonly expressed through the request-response communication between a client and a server. The client is any front-end application that a user interacts with.
The server is in charge of backend logic and database operations. In this scenario, an API works as a middle layer between the client and the server, making it possible to send data requests and responses.
Most web APIs follow the workflow below:
The user performs a task on a website, app, or software program, such as clicking a video to watch it.
This action tells the site or app to initiate an API call, which means to submit a request to the API for information from the external server or program.
The API then retrieves the requested data and delivers it back to the app so the user has the expected experience.
Cloud APIs enable cloud applications to communicate with one another. As organizations deploy more programs and services on the cloud, cloud APIs will become more vital to how we use the internet.
Types of APIs
There are different types of APIs that can be categorized based on the ways they are available for use and according to their initial design purposes.
Private APIs.
These application software interfaces are designed to improve organizational solutions and services. In-house developers or contractors may use these APIs to integrate a company’s IT systems or applications as well as build new systems or customer-facing apps leveraging existing systems.
Even if apps are publicly accessible, the interface itself remains available only for those working directly with the API publisher. The private strategy allows a company to fully control API usage.
Partner APIs.
This type of API is openly promoted but shared with business partners who have signed an agreement with the publisher. The common use case for partner APIs is software integration between two parties. A company that provides partners with access to data or capability benefits from extra revenue streams. At the same time, it can monitor how the exposed digital assets are used, ensure whether third-party solutions using their APIs provide decent user experience, and maintain corporate identity in their apps.
Public APIs.
Also known as developer-facing or external, these APIs are available for any third-party developers. A public API program allows for increasing brand awareness and receiving an additional source of income when properly executed.
There are two types of public APIs – open (free of charge) and commercial ones.
Open public APIs, as the Open API Definition suggests, are those with all features public and available for use without restrictive terms and conditions. For instance, it’s possible to build an application that utilizes the API without explicit approval from the API supplier or mandatory licensing fees. The definition also states that the API description and any related documentation must be openly available. On top of that, these APIs can be freely used to create and test applications.
Commercial API users pay subscription fees or use APIs on a pay-as-you-go basis. A popular approach among publishers is to offer free trials, so users can evaluate APIs before purchasing subscriptions. Learn more about how businesses benefit from opening their APIs for public use in our detailed article on the API economy.
APIs by use cases
APIs can be classified according to the systems for which they are designed.
Database APIs.
Database APIs enable communication between an application and a database management system. Developers work with databases by writing queries to access data, change tables, etc. The Drupal 7 Database API, for example, allows users to write unified queries for different databases, both proprietary and open source (Oracle, MongoDB, PostgreSQL, MySQL, CouchDB, and MSSQL).
Another example is ORDS database API, which is embedded in Oracle REST Data Services.
Operating systems APIs.
This group of APIs defines how applications use the resources and services of operating systems. Every OS has its set of APIs, for instance, Windows API or Linux API (kernel user-space API and kernel internal API).
Apple provides API references for macOS and iOS in its developer documentation. APIs for building applications for Apple’s macOS desktop operating system are included in the Cocoa set of developer tools. Those building apps for the iOS mobile operating system use Cocoa Touch – a modified version of Cocoa.
Remote APIs.
Remote APIs define standards of interaction for applications running on different machines. In other words, one software product accesses resources located outside the device that requests them, which explains the name. Since two remotely located applications are connected over a communications network, particularly the internet, most remote APIs are written based on web standards. Java Database Connectivity API and Java Remote Method Invocation API are two examples of remote application programming interfaces.
Web APIs.
This API class is the most common. Web APIs provide machine-readable data and functionality transfer between web-based systems which represent client-server architecture. These APIs mainly deliver requests from web applications and responses from servers using Hypertext Transfer Protocol (HTTP).
Developers can use web APIs to extend the functionality of their apps or sites. For instance, the Pinterest API comes with tools for adding users' Pinterest data like boards or Pins to a website. Google Maps API enables the addition of a map with an organization’s location.
Most businesses use more than one API to connect applications and share information. Some end up needing an API management tool to help them control, distribute, and analyze different APIs. Learn more about API management in our detailed article.
API specifications/protocols
The goal of API specifications is to standardize data exchange between web services. In this case, standardization means the ability of diverse systems, written in different programming languages and/or running on different OSs, or using different technologies, to seamlessly communicate with each other.
Remote Procedure Call (RPC)
Web APIs may adhere to resource exchange principles based on a Remote Procedure Call or RPC. This protocol specifies the interaction between applications based on the client-server architecture. One program (client) requests data or functionality from another program (server), located in another computer on a network, and the server sends the required response.
RPC is also known as a subroutine or function call. One of two ways to implement a remote procedure call is SOAP.
How RPC works
A client invokes a remote procedure, serializes the parameters and additional information into a message, and sends the message to a server. On receiving the message, the server deserializes its content, executes the requested operation, and sends a result back to the client. The server stub and client stub take care of the serialization and deserialization of the parameters.
RPC Pros
Straightforward and simple interaction.
RPC uses GET to fetch information and POST for everything else. The mechanics of the interaction between a server and a client come down to calling an endpoint and getting a response.
Easy-to-add functions.
If we get a new requirement for our API, we can easily add another endpoint executing this requirement: 1) Write a new function and throw it behind an endpoint and 2) now a client can hit this endpoint and get the info meeting the set requirement.
High performance.
Lightweight payloads go easy on the network providing high performance, which is important for shared servers and for parallel computations executing on networks of workstations. RPC is able to optimize the network layer and make it very efficient with sending tons of messages per day between different services.
RPC Cons
Tight coupling to the underlying system.
An API’s abstraction level contributes to its reusability. The tighter it is to the underlying system, the less reusable it will be for other systems. RPC’s tight coupling to the underlying system doesn’t allow for an abstraction layer between the functions in the system and the external API. This raises security issues as it’s quite easy to leak implementation details about the underlying system into the API. An RPC’s tight coupling makes scalability requirements and loosely coupled teams hard to achieve. So, the client either worries about any possible side effects of calling a particular endpoint or tries figuring out what endpoint to call because it doesn’t understand how the server is naming its functions.
Low discoverability.
In RPC there’s no way to introspect the API or send a request and start understanding what function to call based on its requests.
Function explosion.
It’s so easy to create new functions. So, instead of editing the existing ones, we create new ones ending up with a huge list of overlapping functions that are hard to understand.
RPC use cases
The RPC pattern started being used around the 80s, but this doesn’t automatically make it obsolete. Big companies like Google, Facebook (Apache Thrift), and Twitch (Twirp) are using RPC high-performance variates internally to perform extremely high-performance, low-overhead messaging. Their massive microservices systems require internal communication to be clear while arranged in short messages.
Command API.
An RPC is the proper choice for sending commands to a remote system. For instance, a Slack API is very command-focused: Join a channel, leave a channel, send a message. So, the designers of the Slack API modeled it in an RPC-like style making it small, tight, and easy to use.
Customer-specific APIs for internal microservices.
Having direct integration between a single provider and consumer, we don’t want to spend a lot of time transmitting a lot of metadata over the wire, like a REST API does. With high message rate and message performance, gRPC and Twirp are strong cases for microservices. Using HTTP 2 under the hood, gRPC is able to optimize the network layer and make it very efficient with sending tons of messages per day between different services. However, if you’re not aiming at high network performance, but rather at a stable API contact between teams publishing highly distinctive microservices, REST will ensure that.
Service Object Access Protocol (SOAP)
SOAP is an XML-formatted, highly standardized web communication protocol. Released by Microsoft a year after XML-RPC, SOAP inherited a lot from it. When REST followed, they were first used in parallel, but soon REST won the popularity contest.
How SOAP works
XML data format drags behind a lot of formality. Paired with the massive message structure, it makes SOAP the most verbose API style.
A SOAP message is composed of:
an envelope tag that begins and ends every message,
a body containing the request or response
a header if a message must determine any specifics or extra requirements, and
a fault informing of any errors that can occur throughout the request processing.
The SOAP API logic is written in Web Service Description Language (WSDL). This API description language defines the endpoints and describes all processes that can be performed. This allows different programming languages and IDEs to quickly set up communication.
SOAP supports both stateful and stateless messaging. In a stateful scenario, the server stores the received information that can be really heavy. But it’s justified for operations involving multiple parties and complex transactions.
Extensible markup language (XML) is a simple and very flexible text format widely used for data storage and exchange over the internet or other networks. XML defines a set of rules for encoding documents in a format that both humans and machines can read. The markup language is a collection of symbols that can be placed in the text to delineate and label the parts of the text document. XML text documents contain self-descriptive tags of data objects, which makes them easily readable.
SOAP is mostly used with enterprise web-based software to ensure the high security of transmitted data. SOAP APIs are preferred among providers of payment gateways, identity management, and CRM solutions, as well as financial and telecommunication services. PayPal’s public API is one of the commonly known SOAP APIs. It’s also frequently used for legacy system support.
SOAP pros
Language- and platform-agnostic.
The built-in functionality to create web-based services allows SOAP to handle communications and make responses language- and platform-independent.
Bound to a variety of transport protocols.
SOAP is flexible in terms of transfer protocols to accommodate for multiple scenarios.
Built-in error handling.
SOAP API specification allows for returning the Retry XML message with error code and its explanation.
A number of security extensions.
Integrated with the WS-Security protocols, SOAP meets an enterprise-grade transaction quality. It provides privacy and integrity inside the transactions while allowing for encryption on the message level.
SOAP cons
These days, many developers shudder at the idea of having to integrate a SOAP API for several reasons.
XML only.
SOAP messages contain a lot of metadata and only support verbose XML structures for requests and responses.
Heavyweight.
Due to the large size of XML-files, SOAP services require a large bandwidth.
Narrowly specialized knowledge.
Building SOAP API servers requires a deep understanding of all protocols involved and their highly restricted rules.
Tedious message updating.
Requiring additional effort to add or remove the message properties, rigid SOAP schema slows down adoption.
SOAP use cases
Right now, the SOAP architecture is most commonly used for internal integration within enterprises or with their trusted partners.
Highly secured data transmission.
SOAP rigid structure, security and authorization capabilities make it the most suitable option for enforcing a formal software contract between API and client while complying with the legal contract between the API provider and API consumer. That’s why financial organizations and other corporate users opt for SOAP.
Representational State Transfer (REST)
The term REST was introduced by computer scientist Roy Fielding in a dissertation in 2000. Unlike SOAP, which is a protocol, REST is a software architectural style with six constraints for building applications that work over HTTP, often web services. The World Wide Web is the most common realization and application of this architectural style.
REST is considered a simpler alternative to SOAP, which many developers find difficult to use because it requires writing a lot of code to complete every task and following the XML structure for every message sent. REST follows another logic since it makes data available as resources. Each resource is represented by a unique URL, and one can request this resource by providing its URL.
Web APIs that comply with REST architectural constraints are called RESTful APIs. These APIs use HTTP requests (AKA methods or verbs) to work with resources: GET, PUT, HEAD, POST, PATCH, CONNECT, TRACE, OPTIONS and DELETE.
RESTful systems support messaging in different formats, such as plain text, HTML, YAML, XML, and JSON, while SOAP only allows XML. 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 these days.
Social media giants and travel companies provide external APIs to improve their brand visibility even more. Twitter has numerous RESTful APIs; Expedia has both SOAP and RESTful APIs for its partners.
JavaScript Object Notation (JSON) is a lightweight and easy-to-parse text format for data exchange. Its syntax is based on a subset of the Standard ECMA-262 3rd Edition. Each JSON file contains collections of name/value pairs and ordered lists of values. Since these are universal data structures, the format can be used with any programming language.
JSON has been widely adopted thanks to the popularity of REST.
How REST works
REST isn’t as strictly defined as SOAP. RESTful architecture should comply with six architectural constraints:
uniform interface: permitting a uniform way of interacting with a given server regardless of device or application type
stateless: the necessary state to handle the request as contained within the request itself and without the server storing anything related to the session
caching
client-server architecture: allowing for independent evolution of either side
layered system of the application
the ability for servers to provide executable code to the client
In REST, things are done using HTTP methods such as GET, POST, PUT, DELETE, OPTIONS, and, hopefully, PATCH.
REST pros
Decoupled client and server.
Decoupling the client and the server as much as possible, REST allows for a better abstraction than RPC. A system with abstraction levels is able to encapsulate its details to better identify and sustain its properties. This makes a REST API flexible enough to evolve over time while remaining a stable system.
Discoverability.
Communication between the client and server describes everything so that no external documentation is required to understand how to interact with the REST API.
Cache-friendly.
Reusing a lot of HTTP tools, REST is the only style that allows caching data on the HTTP level. In contrast, caching implementation on any other API will require configuring an additional cache module.
Multiple formats support.
The ability to support multiple formats for storing and exchanging data is one of the reasons REST is currently a prevailing choice for building public APIs.
REST cons:
No single REST structure.
There’s no exact right way to build a REST API. How to model resources and which resources to model will depend on each scenario. This makes REST simple in theory, but difficult in practice.
Big payloads.
REST returns a lot of rich metadata so that the client can understand everything necessary about the state of the application just from its responses. And this chattiness is no big deal for a big network pipe with lots of bandwidth capacity. But that's not always the case. This was the key driving factor for Facebook coming up with the description of GraphQL style in 2012.
Over- and under-fetching problems.
Containing either too much data or not enough of it, REST responses often create the need for another request.
REST use cases
Management APIs.
APIs focused on managing objects in a system and intended for many consumers are the most common API type. REST helps such APIs to have strong discoverability, good documentation, and it fits this object model well.
Simple resource-driven apps.
REST is a valuable approach for connecting resource-driven apps that don’t need flexibility in queries.
gRPC
gRPC is an open-source universal API framework that is also classified under RPC. Unlike SOAP, gRPC is much newer and was released publicly in 2015 by Google. With gRPC, the client application can directly call methods from a server application located on a different computer as if it was a local object. This makes it easier to create distributed services and applications.
Like SOAP and REST, the transport layer for gRPC is HTTP. However, similar to RCP, gRPC allows developers to define any kind of function calls, rather than selecting from predefined options such as PUT and GET in the case of REST.
By default, gRPC uses protocol buffers instead of JSON or XML as the Interface Definition Language (IDL) for serializing structured data. Here, the developer needs to first define the structure of the data they want to serialize. Once the data structures have been specified, they use the protocol buffer compiler to generate the data access classes in the programming language of your choice. The data is then compressed and serialized in binary format at runtime.
gRPC is mostly used for communication between microservices because it is available in multiple languages and has a high performance.
GraphQL
It takes a number of calls to the REST API for it to return the needed staff. So GraphQL was invented to be a game-changer.
GraphQL is a syntax that describes how to make a precise data request. Implementing GraphQL is worth it for an application’s data model with a lot of complex entities referencing each other.
The need for faster feature development, more efficient data loading due to increased mobile adoption, and a multitude of clients, made the developers look for other approaches to software architecture. GraphQL, initially created by Facebook in 2012 for internal use, is the new REST with organizations like Shopify, Yelp, GitHub, Coursera, and The New York Times, using it to build APIs.
GraphQL is a query language for APIs. It allows the client to detail the exact data it needs and simplifies data aggregation from multiple sources, so the developer can use one API call to request all needed data. Another special feature of GraphQL is that it uses a type system to describe data.
Using types to describe data allows apps to specify what data they need to get
How GraphQL works
GraphQL starts with building aschema,which is a description of all the queries you can possibly make in a GraphQL API and all thetypesthat they return. Schema-building is hard as it requires strong typing in the Schema Definition Language (SDL).
Having the schema before querying, a client can validate their query against making sure the server will be able to respond to it. On reaching the backend application, a GraphQL operation is interpreted against the entire schema, and resolved with data for the frontend application. Sending one massive query to the server, the API returns a JSON response with exactly the shape of the data we asked for.
Query execution in GraphQL, Source:
In addition to the RESTful CRUD operations, GraphQL has subscriptions allowing for real-time notifications from the server.
GraphQL pros
Typed schema.
GraphQL publishes in advance what it can do, which improves its discoverability. By pointing a client at the GraphQL API, we can find out what queries are available.
Fits graph-like data very well.
Data that goes far into linked relations but not good for flat data.
No versioning.
The best practice with versioning is not to version the API at all.
While REST offers multiple API versions, GraphQL uses a single, evolving version that gives continuous access to new features and contributes to cleaner, more maintainable server code.
Detailed error messages.
In a similar fashion to SOAP, GraphQL provides details to errors that occurred. Its error message includes all the resolvers and refers to the exact query part at fault.
Flexible permissions.
GraphQL allows for selectively exposing certain functions while preserving private information. Meanwhile, REST architecture doesn’t reveal data in portions. It’s either all or nothing.
GraphQL cons
Performance issues.
GraphQL trades off complexity for its power. Having too many nested fields in one request can lead to system overload. So, REST remains a better option for complex queries.
Caching complexity.
As GraphQL isn’t reusing HTTP caching semantics, it requires a custom caching effort.
A lot of pre-development education.
Not having enough time to figure out GraphQL niche operations and SDL, many projects decide to follow the well-known path of REST.
Apps using GraphQL control what data they need to fetch from a server, which allows them to run fast even when the mobile connection is slow
GraphQL use cases
Mobile API.
In this case, network performance and single message payload optimization is important. So, GraphQL offers a more efficient data loading for mobile devices.
Complex systems and microservices.
GraphQL is able to hide the complexity of multiple systems integration behind its API. Aggregating data from multiple places, it merges them into one global schema. This is particularly relevant for legacy infrastructures or third-party APIs that have expanded over time.
Comparing API Architectural Styles: SOAP vs REST vs GraphQL vs RPC
Today, many API consumers refer to REST as “REST in peace” and cheer for GraphQL, while ten years ago it was a reverse story with REST as the winner to replace SOAP. The problem with these opinions is that they are one-sided picking a technology itself instead of considering how its actual properties and characteristics match the situation at hand.
lets discuss the four major API styles in the order of their appearance, compare their strong and weak sides, and highlight the scenarios where each of them fits best.
Which API pattern fits your use case best?
Every API project has different requirements and needs. Usually, the architectural choice depends on
the programming language in use,
the environment in which you’re developing, and
the resources you have to spare, both human and financial.
Knowing all the tradeoffs that go into each design style, API designers can pick the one that’s going to fit the project best.
With its tight coupling, RPC works for internal microservices but it’s not an option for a strong external API or an API service.
SOAP is troublesome but its rich security features remain irreplaceable for billing operations, booking systems, and payments.
REST has the highest abstraction and best modeling of the API. But it tends to be heavier on the wire and chattier - a downside if you’re working on mobile.
GraphQL is a big step forward in terms of data fetching but not everyone has enough time and effort to get the hang of it.
Examples of APIs
Here are some examples of well-known APIs that use different protocols and specifications. Check their documentation to get more information and references.
Google Maps.
It is no secret that Google is among the tech giants, and they have set the standards in the way other companies operate. Most websites that have an integrated map are using the Google Maps APIs. For example, Google’s Directions API uses an HTTP request to return XML or JSON-formatted directions between geolocations.
Vulkan.
Vulkan is a cross-platform API that works on the operating system level. It enables developers to create high-quality, real-time graphics in applications and drives the communication between an application and a graphical processing unit. Check Vulkan API documentation if you’re interested.
Skyscanner Flight Search.
Skyscanner is a metasearch platform that lets travelers look for flights at the best rates from Skyscanner’s database of prices. Also, Skyscanner provides its affiliate partners with a RESTful API supporting both XML and JSON as the data exchange formats. In order to improve security, they encourage partners to only use HTTPS protocol to make requests. You may check their documentation here.
WeatherAPI.
This is a free geolocation and weather information provider with lots of different APIs ranging from the weather forecast, IP lookup, sports, astronomy, geolocation, and time zone. It provides access to geodata and weather using a JSON/XML RESTful API. Developers can use either HTTP or HTTPS to request the API. They provide developers with detailed documentation on how to use all of their APIs.
Sabre Air Availability.
This is a Sabre SOAP API used to search for flights and the corresponding availability information for given dates, origins, and destinations. Since it is a SOAP API, it uses XML as the data exchange format, and HTTP or HTTPS protocols for requests.
Yelp API.
This is a GraphQL API that provides users with recommendations and reviews of the best restaurants, things to do, nightlife, and more. It uses the HTTP request method to access data from the servers. The API connects to data sources through endpoints, which developers can add to their apps. It uses JSON as the data exchange format.
Conclusion
In conclusion, our exploration of APIs reveals them as the unsung heroes behind the seamless connectivity and innovation that define our digital landscape. As we've delved into the intricacies of Application Programming Interfaces, it's clear that they are not just lines of code facilitating communication between software systems; they are enablers of efficiency, collaboration, and transformative change.
In a world where data is king, APIs emerge as the gatekeepers, controlling the flow of information between applications. As developers, businesses, and technology enthusiasts, embracing the potential of APIs opens doors to creativity, collaboration, and efficiency. So, let's continue to harness the power of APIs responsibly, pushing the boundaries of what's possible and creating a connected digital ecosystem that benefits us all. The journey with APIs is ongoing, and the possibilities are limitless – here's to the next frontier of innovation!
That's a wrap. Thanks for reading.
Hope this article was helpful to you.
If you enjoyed reading this, then please like and share this article with others.
Have fun coding!