Beginners Guide to API

The term API and its concepts are nothing new. There are many categories of APIs: APIs from software libraries and frameworks, APIs from operating systems, remote APIs, and Web APIs. When we talk about APIs, we talk about the latter, i.e., Web APIs.

Exposing an organization’s assets and digital products became straightforward with the advent of API management platforms. And this was the trigger for many organization to start exposing their assets via APIs. In many cases, however, this inside-out approach didn’t met people’s expectation. Between you and me: this was exactly how we started.

The terminology of API spans a range of technical, organisational, and economical topics. And often, people mix terms, used them interchangeably, and abbreviate when ever possible.

In this chapter, we explain all terms relevant to understand the world of APIs.

In the following, we’ll clarify what APIs are and what perspective on APIs leads to successful APIs in terms of business value and success. Furthermore, we’ll explain what an API management platform is and how to use it. Finally, we’ll discuss the main stakeholders.

What is an API?

Typically, we all use software applications via a user interface. Just imagine all the apps on your smart phone and how you click on the display to interact with these apps.

Similarly, software applications can interact and use other software applications. In contrast to a user interface, they do it via a machine interface, which we call API. In other words, an API is a set of functions that allows creating applications that access the features or data of another application or service.

API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. For instance, each time you use an app like Facebook, send an instant message, or check the weather on your smart phone, you’re using an API.

APIs are the user interface for applications to interact with and use other applications.

Just as a graphical user interface on a smart phone makes it easier for people to interact with apps, so APIs make it easier for developers to use technologies, applications, or backend systems. Generally, an API simplifies programming by abstracting the underlying implementation.

An app that combines multiple APIs is known as mashup.

The following figure represents the interaction between various entities. In the following, we explain the entities that are relevant in the context of API.

The API client send a request to the API proxy, which processes it and sends it to the backend system. The API proxy waits for the backend system’s response, processes it and returns a response back to the API client.

API Client

The API client is the application of the API customer that uses the API. It sends requests to the API and receives responses back.

Generally, the API client serves an end-users. The usage of the API clients creates business value for the API customer. For example, an end-user wants to register on a Web site (API client) and enters among other things his e-mail address. The Web site uses an API to verify the end-users e-mail address. To this goal, a verification e-mail is sent to the end-user.

The API consumer controls the API client. That means the API consumer controls when and how to use the API. The API provider, however, may provide a software development kit (SDK) to facilitate the API client’s interaction with the API and get more control about how the API client uses the API.

Backend System

The backend system represents the asset of the organization. It can be a database, a software application, or a service.

API Proxy

The API proxy implements the API. More specifically, it is the piece of software running on an API runtime platform that receives requests from an API client, interacts with backend systems, and sends responses back to the API client.

The API proxy decouples the API from the backend systems. Hence, it can be updated or replaced with another API proxy without API clients noticing it. Typically, the API proxy adds security to protect the backend system and data owners. To this goal, it authenticates API client and checks if it is authorized. Further, it may limit interactions with the backend systems to protect them from overloading.

The API proxy is a software artefact. It can be deployed on an API runtime platform. Typically, multiple API proxies together implement one API.

The API provider builds, deploys, and operates API proxy.

API Feature

The API feature describes one possible interaction with the API. Generally, multiple API features constitute an API.

The documentation of an API contains primarily the documentation of its containing API features.

An API proxy implements one or more API features.

Typically, an API product manager defines the API feature. To this goal, the API product managers may collaborate with an API specialist who can translate the API feature into a sound API design.

API

The API consists of multiple API features, typically from one domain. Typically, an organization’s asset or rather backend system (e.g., customers) defines the domain.

The API defines how an API client can interact with it and what the API client can expect from it in terms of responses and changes in the backend systems (e.g., creating and persisting objects). Ultimately, the API is a technical contract how API clients can interact with backend system. However, the term API is often used instead of API product or API proxy.

The API has a marketing name. Typically, the solution (e.g., Identity API), value proposition (Identity Verification API), data (e.g., Customer API) or the backend system (e.g., Customer Relationship Management API) provides the name.

The API provider defines and specifies the API. Nevertheless, the API consumer might be taken into consideration to evolve the API. This refers to the API evolution pattern of consumer-driven contracts.

Anatomy of an API

After having developed more than 100 APIs, we thought it’s time to analyze our APIs for some common patterns to formulate an API benchmark. This can be used for effort estimation, quality control, and API governance.

I> coming soon!

What is a Digital Product?

An API product is more than just a technical API. The following figure shows that an API product consists of APIs and API features. The left side shows the business perspective of APIs. A digital product refers to an API product. Business feature, are feature that describe how a business value is created. They refer to API features.

The API perspective shows the API terminology. An API product consists of APIs and API features. An API consists of API features. An API proxy implements some API features.
The business perspective shows the business terminology.

In the following, we explain the terminology of the API and business perspective and how they relate to each other.

API Product

Technically, an API product is a bundle of multiple API features and APIs and a revenue model.

The API product provides the required set of APIs and API feature to solve a common problem. API customers buy for the usage of an API product. Hence, the API product has a price plan attached.

The API product manager defines the API product and the revenue model.

Business Feature

Customers have jobs they need to get done. Customer problems are the pains customer have to get their jobs done. The business feature is a pain reliever that relieves one or more customer pains. For example, a business feature can

The set of business features that help a customer to get his job done is the value proposition.

Digital Product

A digital product consists of multiple business features and has a value proposition.

In fact, an API product is a digital product. The digital product is solution technology agnostic, however. Today, it’s APIs. Tomorrow, it might be something another technology. For that reason, we refer to API products often as digital products.

Minimum Viable API Product

A minimum viable product (MVP) is a product with just enough features to satisfy early customers. In fact, An MVP is a minimum desirable, feasible, and viable product. An MVP is very useful to get early customers and test it on the market. The following figure explains how to build an MVP.

A minimum viable product (MVP) provides enough features that it provides a value to an early customer.

The concept of MVP applies to APIs too. As depicted in the following figure, an MVP consists at least of an API product, an API, an API feature, and an API proxy.

An API-based minimal viable product (MVP) needs to consists of at least an API proxy, an API feature, an API, and an API product.

Paradigm Shift: From API to VPI

How to not make APIs successful? By limiting APIs to expose interfaces to applications. Yes, you heard it right. Let’s forget for one moment what the acronym of API stands for. It’s not about a programming interface of an application, no it’s not. In fact, an API is an interface to a value proposition! Period.

If I learned one lesson as technical lead of the API program of Swisscom, the biggest Swiss telco provider, and as lean startup practitioner then it’s this: The API is dead, long live the VPI! VPI stands for Value Proposition Interface.

Ultimately, the API is only about the interface to the value proposition, not to the application.

From Inside-Out to Outside-In

Let me share a real story. Some of my colleagues developed a technically sound Customers API. You guess right: the Customers API provides information about customers of the Swiss telco provider. It provides full names, addresses, and subscription info. But honestly, how many companies might be interested to know who are the customers of a Swiss telco and why should they care about their mobile subscriptions? To summarize, the Customers API has not much value for other companies.

My team followed a different approach. We didn’t expose the telco’s customer relationship management (CRM) application via API. We applied the lean startup methodology and looked for relevant problems. And we found one: Digital Customer Onboarding. We found that many companies struggle with converting Online visitors to customers.

We discovered one common theme. The registration process for the digital customer’s onboarding included either verifying IDs, phone numbers, or postal addresses. To this goal, companies asked Online visitors to scan their IDs and upload them. These IDs would then be manually verified, somehow. Or, they letters containing a secret code, by post, to the people at home. Afterwards, people were asked to enter this secret code again on a Web site to verify their address and complete their registration, days later.

Guess what. Such a registration process is too cumbersome and makes the Online visitor drop out from the registration process before completing it. As a result, Online visitors don’t convert to customers, i.e, the conversion rate is poor.

Birth of an API product

Instead of a Customers API, we developed an API that simply verifies the customer info taken from the Web registration form by matching it with the customer info we’ve got in the telco databases. In short:

• Problem: low conversion rate of digital customer on-boarding because of complex and cumbersome registration process.
• Value Proposition: simple and fast verification of an identity or rather of the personal info.
• Solution: an API to verify the identity of a person aka Identity Verification API.

Now, think about how much value such an Identity Verification API provides if compared to a Customers API, which provides just info about a telco’s customer base? Please note that both APIs rely on the  data set. One API, however, is a great success because it has a value proposition built-in.

I realized one thing. Successful APIs in terms of commercial success and reusability have to meet the criteria of a VPI (Value Proposition Interface).

A VPI is an interface to exploit a value proposition.

Having this mindset, you’ll be able to create relevant APIs that are commercially successful, are reused, and provide value.

What is an API Management Platform?

Typically, an API management platform consists of three platform components: API development platform, API runtime platform, API engagement platform.

API Development Platform

The API development platform enables API providers to develop APIs quickly and with high quality. To this goal, it offers a toolbox with common API building blocks (e.g., data transformation, authentication, logging, value extraction) that are proven, reusable, and configurable.

API Runtime Platform

The API runtime platform enables the execution of the APIs. It enables the API to receive requests from apps or Web sites and send responses back. Most commonly, the API platform is an HTTP server, which allows exposing services via HTTP. HTTP is the common protocol for REST APIs.

The user experience depends on the availability, throughput, stability, and security of APIs and the API runtime. For this reason, the API runtime platform provides capabilities for caching, load balancing, and connection pooling. Further, it provides capabilities for monitoring, logging, and analytics that helps operators to measure and ensure this non-functional properties.

Further, the API runtime platform provides API providers capabilities to smoothly deploy new APIs or maintenance of existing ones.

API Engagement Platform

The API engagement platform enables the interaction between API provider and API customer and consumer. The API engagement platform provides capabilities for customer and consumer onboarding, API product catalog and corresponding API documentation and instructions.

Interactions Between the Platforms

The three components of an API management platform (i.e., API developer platform, API runtime platform, and API engagement platform) are used together.

API consumer develop an API on the API development platform. Then, they deploy and run it on the API runtime platform. Then, they publish the API and the documentation in the API engagement platform.

API consumer develop an API on the API development platform. To this goal, they use the provided building blocks to build APIs.  Then, they deploy and run it on the API runtime platform. Typically, organizations will have multiple environments for developing, testing, integrating, and releasing in production. Lastly, the API is added to the API catalog and the API documentation is published on the API engagement platform.

Who are the API Stakeholders?

There are four main groups of stakeholders: API providers, API customers, API consumers, and end-users. API providers build, expose, and operate APIs. API customers decide what API to buy or rather the usage of the API. API consumers develop apps that use APIs. End-users don’t use directly APIs. Instead, they use APIs indirectly via the app that is developed by the API consumer and provided by the API customer.

The following figure shows the four main groups and how they interact.

Stakeholders of APIs: API provider, API customer, API consumer, end-user

In the following, we describe each group, their competencies, as well as heir interests.

API Provider

API providers build, expose, and operate APIs. In other words, API providers are the ones that provide APIs to others.

API providers need to know how to design, build, and operate APIs.

Typically, API providers use an API management platform to build, expose, and operate APIs. Further, they provide a developer portal to engage with API customers and API consumers.

API Customer

API customers are the ones who decide what APIs to use, especially commercial APIs.

Generally, API customers have a problem or rather job they want getting done. More precisely, API customers look for solutions to their problems. Since they don’t have the resources, the time, or the right data, they choose APIs from API providers. Using APIs can boost time-to-market enormously.

To find the right APIs, API customers are looking for the API with the right value proposition. For that reasons, it is paramount for the API provider to present their APIs as interface to a value proposition and present their unique value proposition (USP).

API Consumer

API consumers develop software applications or Web sites that use APIs. Typically, they are the developers who integrate APIs in their apps or Web sites. In other words, API consumers are the users of APIs. Often, they are mistaken as the customers. They aren’t.

API consumers are probably the most important stakeholders for API providers because they interact the most with the APIs and the developer portal.

API consumers look for simple APIs, good documentation, and instructions how to use the APIs. They are the main users of the developer portal. On the developer portal, they look API credentials to use the API, API documentation, SDKs, and an API sandbox.

End-Users

End-users don’t use APIs directly. Instead, they use apps or Web sites that use APIs in the background.

Nevertheless, the availability, performance, and security of your APIs have a direct impact on the user experience of end-users. A bad end-user experience leads to unsatisfied API customers and API consumers. As a result, they might look for alternatives to your API.

Summary

The API management platform consists of three platforms:

• API development platform: enables API providers to develop APIs quickly and with high quality
• API runtime platform: enables the execution of the APIs. It enables the API to receive requests from apps or Web sites and send responses back.
• API engagement platform: enables the interaction between API provider and API customer and consumer. It provides a catalog of APIs with documentation and instructions.

The stakeholders consists of four main groups:

• API providers: build, expose, and operate APIs
• API customers: decide what API to use and pay the usage of the API
• API consumers: develop apps that use APIs
• End-users: don’t use APIs directly. Instead, they use apps that make use of APIs.