This site is in beta. Tell us what you think.
Chapter 1 | APIs Guidebook

Introduction to APIs

One of the most crucial building blocks of data-driven value is the API. API stands for Application Program Interface, a standardized way to pass data and commands between various systems to help them work together stably and securely.

APIs enable developers to connect various apps and devices without reinventing common functions or merging different operations, and which allows for both human-to-machine and machine-to-machine interactions.

To do this, APIs require robust architecture and clarity about how the data is structured. Otherwise, apps that read or alter the data in different ways could have unintended results.

Example

Authentication APIs

For example, every time you use Facebook to log into another website, like Airbnb, you're using an authentication API. Facebook confirms to Airbnb that you're who you say, without you having to set up a separate username and password. There are rules about what data can and cannot be passed back and forth between systems with Facebook. These rules can either protect or compromise your privacy, depending on the situation.

Third-party apps don't necessarily get to access everything about your Facebook profile and might only be able to see, for example, your email address.

A screen shot of a common log in or sign up form on the Airbnb website.

APIs allow you to use data quickly without needing to build a lot of new infrastructure. Once you have determined your intended use of data, consider whether you could use an API and related software development kits (SDKs) to make it happen quickly.

The case for APIs

To benefit from APIs, companies need to rethink their infrastructure. From the early days of digital computers to the 1990s and early 2000s, companies integrated information technology into their existing processes in order to streamline production and sales. Most gains with early technologies were created through improved efficiency.

But in the Digital Age, technology’s role now shifts from optimizing production to powering platforms.

Given today’s user expectations, new infrastructure creates entry points for participation, allowing users and strategic partners to co-create, consume, and extract value in surprising ways.

Shifting from 'IT as a utility' to 'digital as a capability'

One significant change that digital opportunities require of traditional firms is broadening their concept of where technology functions are located in the company and how it is applied. Traditional information technology skills and infrastructures such as networking, database management, and internet access are more important than ever. However, organizations must shift their focus from IT as a utility—basically confined to a single department in a business—to digital as a capability in every part of the business. IT doesn't stop supporting basic functions of the business—instead, it starts providing and connecting components needed for new and exciting digital value propositions.

IT used to be thought of as the 'pipes' of the business world: a necessary expense that ensured the functioning of material processes like products manufacturing or service sales.

In other words, IT was a utility that enabled analog products to function more smoothly. Initially, these systems comprised only a few key technologies and datasets. But as more users, institutions, and datasets were added on, technology strategies became ever more complex, causing massive challenges when one company needed to connect to (or had acquired) another.

A classic example is the acquisition of Continental Airlines by United Airlines in the US—the merging of their two IT infrastructures took countless years.

Technologies of the early IT mindset were usually focused on what happens inside the walls of the company. Consequently, they tend to be closed to other systems, proprietary and difficult for users to access. We can think of this era as "IT-streamlined" but not fully digital; most forms of value creation are still limited to business models and offerings which would be recognizable to someone who wasn't aware of computers.

Because of this, less attention was paid to interoperability and user interface than was paid to basic functioning. Value creation for companies with this mindset tends to be limited to a linear, analog perspective, that of 'pipes.'

The pipes-based model of IT focused on streamlining sales and production but didn't provide capabilities for creating new value. In the old model, infrastructure is a cost center, and it requires its host organization to conceive of, design, and deliver all value to the customer.

As technology and infrastructure components advanced, they became more heterogeneous. Fierce competition in the software and hardware industries often resulted in infrastructure becoming a tangled mess of interdependencies. Custom solutions were built for individual companies or even for different departments within the same company.

Digital infrastructure became hard to manage, secure, and keep within budget.

In many industries, this spawned multi-sided platform business models, and within companies, it often resulted in the creation of similar platforms for creating value inside the organization.

Organizations, and the individuals within them, must embrace data and APIs to ensure they can offer value in today's shifting digital landscape.

Companies need to shift mental models throughout their organization to think of 'digital' as a capability, rather than IT as only a utility function, so that we're able to strategically capture data and organize it into meaningful information.

In order to do this, each person in the firm must have at least a conversational ability—if not fluency—in top technologies which affect and power their business.

For example, in many companies marketing and branding departments were the first business units to bring their own technology savvy to bear on their work, sometimes in conflict with existing IT policy.  Whether through third-party vendors like agencies or because they chose to hire their own technologists, these departments have shown us that IT cannot be limited to a ‘come and fix it’ utility within the business.

This poses great challenges for IT organizations as they sort out the cost centers of the business—tangled webs of interdependent technologies—inside companies while also trying to launch new revenue-generating functions.

For a tangible example of how such 'enterprise architecture' thinking needs to be expanded, watch ArchiMate’s great whiteboard animation of the importance of enterprise architecture in a platform-based business.

This shift in thinking from monolithic infrastructure into a platform model affects companies in the following key ways:

1. Infrastructure inside companies is modernizing—either by plan or as a response to security needs and IT market forces.

2. Many organizations are connecting with their customers and partners through cloud and API tools.

3. Some organizations directly monetize their data and infrastructure, moving it from a cost center to a revenue center.

4. A few organizations are hosting multi-sided platforms, marketplaces of ideas, data, and applications which other companies and individual users are participating in

APIs enable all of these changes:

1. Inside companies, APIs connect different data and systems which don't already work together, like connecting different Microsoft Office applications.

2. Between organizations, APIs allow for standardized communication, and coordinated operations of, machine systems.

3. APIs allow data and infrastructure to be monetized in a standardized, manageable and metered way, as between financial institutions and Quickbooks accounting software or mobile apps which use Google's image recognition tools.

4. APIs provide connections between users and platforms, and within platforms, the way Apple's HealthKit streamlines secure interconnection and synchronization between native and third-party health apps, devices, and even medical providers and researchers.

APIs' standardization radically lowers the cost and risk of innovating. In this way, they allow network effects to flourish—the exponentially-growing value of a network of people, machines, datasets and developers as more members or 'nodes' get added to it. APIs are the connective tissue that allows people and organizations to quickly and securely create value with data.

What does this evolution from IT-enabled systems to networked platforms look like?

Existing IT-Enabled Systems

Backend infrastructure for internal use only

Siloed and inflexible set of closed systems and data, built for specific goal(s)

Cost center—infrastructure streamlines existing processes but does not attract new customers or create new revenue opportunities

The company creates, delivers, and maintains all value in the customer relationship via a single product or suite of products

New Networked Platforms

Backend infrastructure also interacts with users and partners

Fully open and interoperable systems and data, built for third parties to 'plug and play'

Revenue generator—infrastructure supports a marketplace where third parties can create independent offerings that attract new customers

The company hosts a platform that enables customers, strategic partners, and other third parties to co-create and extract value as well

Computational Thinking

Four puzzle pieces interlocking.

Decomposition:

breaking down a complex problem into several simpler problems

A collection of five sided shapes forming an abstracted icon.

Abstraction:

a model of a system which leaves out unnecessary parts

A stylized illustration of a gear.

Patterns:

using reusable components to minimize error and work

A stylized illustration of a gear rests in the center of a infographic of rectangles connected by lines that multiply in quantity from left to to right.

Algorithms:

a series of unambiguous instructions to process data, make decisions and/or solve problems

A graphic of a one to many series of rectangles indicating multiple choices is contained within a blue box.

Programs:

algorithms converted to programming languages; sometimes called applications

Elsewhere, we've discussed the concept of computational thinking, which is the process of decomposing complex problems into smaller parts, creating models of the world (and tech systems), identifying reusable patterns or components, assembling instructions into algorithms, and creating programs or applications.

Traditional analog companies started by decomposing very complex human problems into select, IT-enabled functions and leaving the rest of the work to be done by humans. Meanwhile, digitally-native companies like Google, Amazon, Facebook, and notable startups, started the other way around. Basically, they only commit to work and offerings that can be managed in an entirely digital toolset.

To over-simplify, analog companies decompose human work into machine functions to operate faster, better, or cheaper. In contrast, digital companies create offerings and business functions in large part by composing (or assembling) different technology functions, using humans only for very high-value or complex tasks which demand the adaptive brain of homo sapiens.

Example

Rideshare Apps

A rideshare app might be composed of several key activities all based around APIs and other reusable components:

  • An app built for a mobile operating system (with many common functions available)
  • Location services (provided by the user's device and its operating system)
  • Mapping (provided by a service like Google Maps)
  • Notifications (through a notifications server managed via API)
  • Chat, text messaging, and phone calls to connect drivers and riders (using an internet-based communications system like Twilio)
  • Collection and distribution of payments (using a payment provider like Stripe)
  • Music (yes, really—Uber piloted a program where a rider could send their music to the driver's phone to play over the car's stereo)

What's important here is that the app developer only needs to develop their own unique functions; they don't need to figure out how to manage users' identities, payment details, etc. Someone else has already built that functionality, and they can access it for free, at low cost for metered access, or as part of a packaged commission, like Apple's app store commissions.

Within the financial industry, there are many different APIs available. Here are some examples that are connected and recombined regularly in everything from disruptive personal budget apps to enormous multinational banks.

Service

Type

Records

Used for

Benzinga

News

Companies, stories, authors

Market intel

Yodlee, Plaid

Financial data portal for individuals

Accounts, investments, transactions, identity, etc.

Quickly creating 'consumer' fintech apps integrated with banks/others

Stripe, PayPal

Merchant services and know-your-customer

Users, payments, transactions, invoices

Enabling e-commerce

Apple Pay, Google Pay, authorize.net

Payment method/wallet

User, card numbers, authorizations

Making digital payments in person or online

Coinbase

Blockchain market/pricing data

Currencies

Understanding crypto positions

Ripple

Currency exchange

Currencies, Ripple's own currency

Reducing payments friction

Bloomberg

Pricing, market data, news

Price, news, etc.

Market intel

Crunchbase, Angellist

Company/startup info

Companies, investors, founders, developers

Tracking and understanding startups

Clearbit

Professional contacts

Individuals, companies, employment history, contact info

Updating CRMs

Example

AWS Data Marketplace

One of the most universal places to explore data and functions available via API is the Marketplace provided by Amazon Web Services (AWS). AWS offers a multi-sided platform where data providers, algorithm developers, and functional consumers are connected through a common core.

AWS makes it easy for all parties to connect securely, usually through APIs. Datasets range from the very specific (like COVID-19 hospitalization data in particular regions) to the very broad (like records of all public flights).

A screenshot from the AWS marketplace with different services offered.

Example

AWS Algorithm Marketplace

Algorithms (data processing functions) are also available on the AWS Marketplace. For example, the work of making a large dataset uniform is costly if you pay humans to do it. Instead, it's possible to pass your data to some robust 'data labeling' services via API and have it returned to you in a more consistent format.

A screenshot of the AWS Algorithm marketplace with different algorithm offerings.

Example

Clearbit

Clearbit is an example of a data enrichment API. Clearbit acquires, aggregates, and normalizes data about individuals, especially professionals. It does this by offering a free service to individuals in a two-way model: In exchange for sharing their address books with the company, their address books are kept current with the most up-to-date contact, title, and employment history.

Clearbit then monetizes that data by making a premium, one-way version available to larger companies who get enriched data without providing data in turn.

A screenshot of a form by clearbit with a pop-up screen with data and code.

Metaphors for APIs

There are several metaphors to make APIs more understandable. Here are a few which can help anyone start to see the implications of APIs.

Cargo & Cargo Ships

A common metaphor for APIs is the idea of cargo ships. Cargo ships connect businesses in different regions with each other, and shuttle a variety of items back and forth in standardized containers. A human conversation between a car dealer and a supplier in another country might go  like this:

  • Do you have any vehicles available?
  • Yes, we have these nine vehicles.
  • Oh, I should have been more specific. I just want cars, not trains or bicycles.
  • Okay, we have seven cars available.
  • Hmm, I only want new-ish cars.
  • Alright, we've got four cars made in the last ten years.
  • Great! Please ship them to me.
  • Alright! I'll put them in a container and put them on the next cargo ship to you.
  • Thanks!

Simultaneously, many other conversations are going on, for many different kinds of goods, and they all get packaged up to make the loading, shipping and unloading of the cargo ship easier. These shipping containers are secure, manageable, and opaque—no one outside can see inside.

APIs provide responses to queries, including very specific queries, and then can send the objects in question securely between systems (just as shipping containers and cargo ships connect various regions and economies).

Electrical Power

APIs are also similar to electrical power. In the early days of electricity, every connection was custom—with different connectors, wire types, frequency, voltage, and amperage.

This was fine for experimenters and early adopters of electricity, but it was very difficult for manufacturers to create safe, reliable electrical products for the mass market.

Therefore, many parts of the world quickly standardized their approach to power transmission. The nature of the power (current types, voltage, and frequency) and the plug shape of the power outlets were established for each region, most of which were very close to a global standard. Within their region, they are compatible with any electrical device on the market, even if manufacturers make adapters to transform the power and plug shape.

Many different devices, ranging from laptops to refrigerators to electric cars, can connect to the same outlets.

Because of this standardization, it was possible for imaginative uses of electricity to flourish and entire manufacturing industries to arise around relatively safe electrical devices.

Pipes

Pipes are a useful metaphor for APIs, too. If we think of data as being like water, as we did when looking at data in motion in the Data Supply Chain, and organizations as buildings or cities, we need a quick and reliable way to move all of that water around.

Compare the idea of moving water around with buckets versus pipes. Buckets require someone to go to some raw source of water, acquire it, and carefully carry it back to where they live or work, filter it and use it—with the risk of spilling or contaminating it along the way. It's a time- and labor-intensive way of moving water around, and certain uses of water just aren't worth the effort.

However, if a plumbing system is built, we can quickly access the right amount of water, correctly filtered, exactly when we need it, and only pay for what we use.

Like pipes, APIs allow us to connect flows of data between various systems, control the supply and demand of data, and even meter and sell it.

Building Blocks

Building blocks, such as Lego, are also a great way to think about data.

Children often accumulate a collection of toys and treasured objects. Adding money to the equation often just exponentially increases the number of toys and their parts strewn around a home. One toy house's window might not fit another toy house's wall.

Between 1910 and 1920, parents started to notice new toys on store shelves: Tinker Toys, Erector Sets, and Lincoln Logs—mix-and-match toy sets that allowed for extended play because they encouraged imaginative recombination of compatible pieces.

Faced with the choice between a single-use toy and a system that children used over and over in new ways, the sets quickly gained popularity.

A few years later, a new entrant (borne out of a necessity for innovation when the Great Depression caused economic chaos) arose: Lego.

By 1960, the interlocking bricks we know today started to gain exponential popularity because of their interoperability, like the modular building sets before them and their precision. Where Lincoln Logs and Tinker Toys used imperfect wood, and erector sets used imprecise metal that could deform, Legos used the novel technology of exact plastic molds.

The more children who used Lego, the more popular they got and the more bricks and other parts parents bought—because of their interoperability and accurate sizing which allowed massive, complex constructions to occur.

Some blocks were generic, and others had particular purposes, like wheels or even integrated motors. But they could all connect to each other.

Just like the mismatched toy parts and early modular systems, trouble occurs when we try to connect different technologies and datasets. Early IT infrastructure was neither stable nor interoperable enough to scale big and run smoothly. But infrastructure designed with building blocks (functions) and interoperable connectors (APIs) means that endless mixing and matching is possible.

With that degree of standardization, abstraction, and interoperable connectors, it is less expensive and in many ways less risky to engage in technology innovation.

APIs connect components inside and between platforms.

An infographic showing the interconnections between API components inside and between platforms. Mastercard/Visa Airbnb Facebook and Android/Apple.

For example, Airbnb's infrastructure extends through API-based connections to payment processors, Facebook, mobile operating systems, and app stores. This allows them to focus on the value created for their users and not on the reinvention of existing infrastructure or requiring customers to re-enter data that already exists in other systems.

There are many, many use cases for APIs, including:

  • Accessing or offering data
  • Processing data
  • Changing or deleting records in other systems
  • Authenticating Users
  • Synchronization
  • Automation
  • Providing ‘leased’ access to data, algorithms and/or computing power
  • Serving up data in real-time

Recombination is key

Calls:
Verbs

Records/Results:
Nouns

...create mashups

Recombination is a key mindset for working with APIs—the mixing and matching of various elements of data and processing functions in different systems to create new value.

In the music world, 'mashups' refers to carefully layering and timing multiple tracks (and 'samples') to create a unique sound. Unlike remixes which might layer a new beat or add a guest appearance by another artist, mashups are significantly different from their original track.

In the same way, recombining bits of data and processing them in new ways can go beyond additive, incremental value to creating something entirely new—or vastly faster or cheaper than a human-mediated approach.

Recombination of APIs usually happens around a couple of key elements.

First, 'calls' are commands passed through an API, like 'get,' 'put' or 'delete.' These calls, which are always verbs, tell a remote system to do things like search, update or delete. These actions are often performed on 'records, or 'objects' which are entries in a database or other system; you can think of these as nouns.

Get

Search for contact records matching "apple" company with name "Johnny Appleseed"

Post

If a record exists, then update the record with new phone number "855-2222222"

If a record doesn't exist, then create a new record with that company, name and phone number

Delete

Delete contact

Role Relationships

Consumer

:

Provider

These requests are communicated through a functional relationship with two parties: a consumer of what the API provider makes available.

In technical contexts, this is often also referred to as a client:server relationship.

Recombination: Mashup

Let's go through a hypothetical example of a very simple algorithm (a script of precise actions for a computer to follow):

RECORD

CALL

API

IF a STORY about ACME is posted on BENZINGA

AND we hold stock in ACME

CREATE a COMPANY in SALESFORCE

THEN GET the STORY AND PUT it in SALESFORCE

In this example, a bank's systems are directed to send a search request (or 'query') to a financial news company, Benzinga, searching for any stories about Acme Incorporated. If there are any stories, the script checks to see if the bank holds stock in that company. If it does, the system will create a new company record in Salesforce (the bank's customer relationship management software), and then get the entire story text from the news service and attach it to that company record.

This used to be a manual operation—the cost of which might have been prohibitive to do at scale. But with APIs and the simplest of algorithms, these three different companies (the bank, Benzinga, and Salesforce) can be connected quickly and pass data and commands between them. In this case, the bank is a 'consumer' for the API 'provider' of Benzinga.

By recombining key functions from several systems, creative individuals inside the bank can automate simple actions that used to take humans a lot of time. They don't necessarily need to know how to manipulate code, either, with modern tools that provide human-friendly interfaces to machine systems.

Far more complex datasets, commands, and instruction sets can be applied here as part of various strategies for machine learning, app development, and other topics out of the scope of this guide. Nearly all modern technology strategies use APIs to connect different datasets and systems to each other.

There are many types of data you might offer, access or manipulate via API. For example, here are just a few record types:

  • Unstructured text
  • Images
  • Maps
  • Transactions
  • Companies
  • Investors
  • Individuals
  • Trends
  • Company structures (holding, subsidiaries)
  • Countries
  • Currencies

To see more, go to the Data Sources Explorer.

APIs allow organizations and even individuals to quickly close the gap between their current, analog way of doing things and digital opportunities.

There are effectively three approaches to creating value with APIs:

  • Building your own APIs to connect systems
  • Buying access to existing APIs (or finding it for free)
  • Partnering with a third party to upgrade infrastructure for APIs.

For more guidance on how to make the decision between those strategies, read the 'Build, Buy or Partner' section of "The Exponential Journey" in our Digital Fluency Guide.

Software Development Kits

Many APIs are provided as part of larger Software Development Kits (or SDKs) which are intended to help developers quickly deploy fast, stable, secure, and consistent software for end-users. Sometimes SDKs have many contributors, like open-source projects; others are provided by one firm to ensure a very consistent experience, like Apple's SDKs for handling health data (HealthKit, ResearchKit and CareKit) or connected home devices (HomeKit).  

Digital companies also often provide SDKs to internal teams or smaller companies developing on their platform for more consistent and stable outcomes. These take the form of a collection of software elements (sometimes as a library or framework) and documentation for how to connect those reusable components with related APIs.

MSP Strategy Questions

A trophy iconA trophy iconA trophy icon

Build

Buy

Partner

Community/Marketplace

...

...

...

Infrastructure

...

...

...

Data

...

...

...

Recap

  • Application Program Interfaces, or APIs, are a standardized way to pass data and commands between various systems to help them work together stably and securely.
  • Organizations are shifting from 'IT as a utility' to 'Digital as a capability'.
  • APIs provide the lowest common denominator between systems, making data and commands available via self-service for machine-to-machine communication.
  • APIs can pass both data and commands.
  • Recombination of data sets and commands accessed via API can allow for quick and reliable digital innovation.

Next Steps:

Get started on a journey to better understand APIs by using two related kinds of Thinking:

  • Design Thinking to understand the elements of a problem or opportunity, and the human needs within it
  • Computational Thinking to decompose that problem or opportunity into the elements needed to create algorithms and applications