Introduction to the Course

APIs, design, and business strategy

Consider a restaurant: a customer places an order, a waiter translates it into a structured request for the kitchen, and the kitchen fulfills it. The customer never interacts with the kitchen directly. This intermediary pattern is fundamental to how software systems communicate.

Understanding interfaces

An Instruction Set Architecture (ISA)This is an interface between hardware and software and is critical for software compatibility. For example, current-generation x86 processors can still run older applications. Interfaces play a critical role in the compatibility of two components. serves as an intermediary between hardware and software. It exposes a set of instructions callable by applications while reserving privileged instructions for the operating system. When software assigns a value to a variable $x$, the compiler and runtime translate that to a memory address and issue hardware instructions via the ISA, abstracting the underlying complexity.

This interface concept extends throughout computing: system calls let applications request OS services, the PCI bus connects peripherals to the motherboard, public class methods define software boundaries, and services like S3 storageSimple Storage Service (S3) is a storage service provided by Amazon Web Services (AWS), accessible through web interfaces. expose interfaces to remote clients. The pattern is universal.

What is an application programming interface?

An application programming interface (API) is an intermediary through which two software components communicate to share data and perform work. The components may reside on the same machine or across a network. The requesting application needs no knowledge of the other's architecture; it only needs to understand the interface for placing requests.

Mapping this back to the restaurant analogy:

• Customers are the software clients requesting a service.

• The waiter is the API, acting as the interface.

• The kitchen and chef are the downstream services, including the serving application and the persistence layerA way to persistently save and retrieve data from the database..

APIs originally enabled communication between software on the same machine. The first network API appeared in the 1970s, exposing services via remote procedure calls (RPCs)An action-oriented (performs functions in terms of actions, such as getProfile) procedure call where the client passes the function name and required arguments to the server to retrieve data.. As the Internet matured, the need for standardization led to web APIs in the late 1990s, which are now the de facto standard for remote application communication.

Benefits of APIs

• Complexity abstraction: APIs hide internal service complexity from consumers, allowing internals to change without modifying the interface. Callers focus solely on the contract and returned data.

• Improved modularity: APIs enable a microservices architecture, breaking applications into flexible, maintainable, reusable service subsets.

• Efficient development: APIs eliminate redundant code by letting developers request services through simple calls, reducing development time and bugs.

• Expedited digitization: APIs accelerated digitization, especially post-COVID-19. According to Moesifblog's summary of a McKinsey report, digital adoption accelerated by the equivalent of six years, with 60% of US businesses employing digital processes.

• Controlled accessibility: APIs enable selective data sharing with restricted user sets and support throttling of service usage frequency.

APIs also serve as a vantage point for usage and performance analytics, helping identify emerging system bottlenecks.

Types of APIs

APIs fall into four types based on user access levels:

• Public APIs expose publicly available data or services. They are freely accessible but typically rate-limited.

• Private APIs are for internal use only, granting the highest access level to internal developers who can see and update backend systems.

• Partner APIs serve users with business relationships to the API owner. They have stronger security than public APIs and are typically purpose-specific, such as granting access to a prepaid service.

• Composite APIs bundle requests to multiple services and return a unified response, reducing the number of API calls and improving efficiency. This is particularly useful in microservice architectures where a single user action may require data from several backend services.

API gateway

The composite API pattern leads directly to the need for a centralized routing layer. Modern applications favor microservices over monolithic architectures for their modularity, flexibility, and ease of independent development.

When a client must interact with multiple microservices simultaneously, making separate API calls to each one degrades performance and increases resource consumption. The API gateway solves this by acting as a single entry point for all API requests, sitting between clients and microservices.

The gateway routes client calls to appropriate microservices, processes composite API parameters, aggregates responses, and returns a unified result. Because APIs can expose valuable data, they are prime targets for cyberattacks, making the gateway's security role critical:

• Provides security, authentication, and rate limiting to protect APIs from overuse.

• Offers monitoring and analysis of user behavior.

• Disseminates a single API call to multiple services and compiles the response.

• Stabilizes the system by balancing network traffic.

API endpoints

With the gateway routing requests, each microservice must be locatable. An endpoint is the digital location (URL) where a service's resources are accessible. API providers define a set of endpoints, each indicating the type of operationsGET, POST, PUT, and DELETE in a REST API. it supports.

Endpoints are accessed by appending the endpoint name to the API's base URL. For example, to retrieve all answers published on the Educative platform, a client sends an HTTP GET request to the corresponding endpoint.

Quiz

What is API design?

With the fundamentals of APIs, gateways, and endpoints established, the next challenge is designing them well. API design is the process of planning and developing programming interfaces that expose data and system functionality to consumers. An effective API design addresses these core questions:

• Why is the API being developed?

• What will be the impact on the system, and what output will it produce?

• How will the API meet the requirements?

• What will the structure of our resources be?

• How will we document our resources?

API design involves efficiently leveraging remote services to satisfy both functional and nonfunctional customer needs while aligning with business goals.

Why does API design matter?

An API is a product. A poorly designed API drives developers to competitors, just as a poorly designed application loses users. Requirements analysis must precede development, and this analysis occurs during the API design phase. The design can be updated iteratively through internal or customer feedback.

API design life cycle

Developers are the customers of the API product. Like any product life cycle, the first phase is designing according to functional and nonfunctional requirements. Developers expect APIs to be simple, helpful, and easy to adopt, so API development follows the same life cycle as other products.

The design-first vs. code-first approach

The code-first approach starts development after business requirements are defined and generates documentation from the code. The design-first approach creates the API's contract or specification document before any code is written.

Code-first suits scenarios that require:

• Quick delivery of the product

• An API for internal use only

• Little or no documentation

Just as constructing a house without architectural plans invites disaster, starting API development without a design-first approach risks costly rework. Specifications often change based on end-user needs, and updating a design is far faster than refactoring code. Early feedback during the design phase prevents future errors.

Note: The design-first approach lets you skip the develop, deploy, and publish stages initially. Instead, a prototypeBy prototyping an API, we mean a specification-oriented user interface that depicts inputs and outputs in a human-readable manner (it might have some code in it). can be used to gather feedback and iterate on the design.

API design considerations

The following key points drive better API design:

• Identify potential users (partners, customers, external developers) to define access levels, authentication mechanisms, and the appropriate architectural style (REST, gRPC, etc.).

• Identify what developer problems the API solves and the metrics it will improve, such as revenue, task speed, cost, and similar indicators.

• Define clear responses (successes and errors), so developers understand the type and reason for each server response. Implement robust exception and error handling alongside well-defined endpoints.

• Apply real-world use cases to validate testability and effectiveness. Analyze performance across different scenarios during the design phase.

• Design for scalability to handle increasing demand without requiring fundamental modifications later.

• Provide adequate documentation covering integration, behaviors, structures, and parameters.

API requirements

Both functional and nonfunctional requirements must be defined:

• Functional requirements define the desired function and its parameters. For example, in a video streaming service, the ability to post comments on a video is a functional requirement with a defined end goal.

• Non-functional requirements define performance and quality, such as low latency for quick responses and scalability for concurrent users, plus availability, reliability, and consistency.

These are generic requirements; the specific list varies by API.

Characteristics of a good API design

APIs have many desirable characteristics. The following is a nonexhaustive list to keep in mind when studying or designing an API. As technology evolves, new characteristics may emerge.

Business considerations with APIs

Beyond design principles, APIs are the foundation of major technology trends. Mobile devices, cloud computing, and IoT all rely on APIs to connect distributed components. As enterprises accelerate digitization, APIs serve as catalysts for this shift.

The role of APIs in modern business strategy

When planning an API, business use cases must be a priority. Organizations that skip this step lack defined goals to measure against. These goals can be driven by revenue, new market opportunities, or new products, but they must all be outlined upfront so that decisions move toward them.

Successful API initiatives focus on one or more of the following factors:

• Monetizing existing assets: APIs can increase the return on investment (ROI) on existing company assets. Companies can expose technical assets to external users and earn ROI through APIs. For example, IBM sells access to Watson for data analytics.

• Connecting business domains: Independent lines of business can benefit from sharing data to streamline processes. Google Workspace is an example: Gmail and Google Drive serve different domains but share data via APIs. In some cases, domains are physical locations (cloud and on-premises data centers), and APIs secure and control data flow between them.

• Self-service: A self-service API portal extends your reach worldwide. Potential clients can discover, test, and integrate features at any time. An easy-to-integrate API is essential; developers who cannot integrate quickly will move to alternatives.

• Innovation: APIs fuel product innovation by providing a simple access point for developers. Google offered its Maps API for integration, enabling ride-sharing apps like Uber and Lyft to build their core business on it, creating value for both providers and consumers.

• Automation: APIs enable enterprise IT teams to automate data transfers between applications, reducing manual processes and custom scripts. This improves efficiency and reliability, speeds up rollouts, and reduces long-term costs.

Note: This list is not exhaustive. APIs can also enable greater customization for developers and help businesses reduce costs.

API business models

Understanding the API value chain is essential before discussing monetization. Three roles define it:

• API providers make business assets available as APIs with defined terms and conditions.

• API consumers are developers using the API under agreed terms to provide services to end users.

• End users/customers benefit from the API indirectly through the applications they use.

The diagram below details this relationship:

Many companies have built their business around APIs. While some are open source, most are premium paid products. The key monetization models are:

• Free: No direct purchases. The API serves a business purpose without direct monetary benefit. Social login APIs from Google and Facebook are examples: providers gain user sign-ups, while some limit free-tier calls to encourage paid subscriptions.

• Developer pays: Charges developers for API usage through several sub-models:

  • Subscription: Monthly or yearly charges. A sandbox for testing or a freemium model (core features are free; premium features are paid) can help convince developers. Convenient for billing, but consumers may pay for unused features.

  • Pay-as-you-go: Also called the usage-based model. Pricing scales with actual usage or call volume. Often cheaper for consumers but harder for providers to bill. AWS exemplifies this approach.

  • Transaction fees: Common with payment gateways like Visa and Mastercard, which charge a fixed percentage per transaction.

• Developer gets paid: The provider incentivizes developers to promote their product:

  • Ads: Developers get paid to include provider advertisements, regardless of end-user engagement.

  • Affiliate: Developers earn when end users click or engage with provider content. Google AdSense is a prime example.

The diagram below summarizes these models and their subtypes:

Performance measures

Beyond monetization, API performance must be measurable and agreed upon by all stakeholders. Business managers, users, and developers may hold different views on quality, which can lead to conflict. Alignment requires formal metrics.

Three tools provide this alignment: service level indicators (SLIs), service level objectives (SLOs), and service level agreements (SLAs). Together, they give developers, business managers, and stakeholders the metrics to drive product decisions.

SLIs

A service level indicator (SLI) is a carefully defined quantitative measure of a specific aspect of the service level provided. Several SLIs can be used, as described in the table below:

SLOs

A service level objective (SLO) is a target range of values for a service measured through an SLI. For the request latency indicator, the structure is as follows:

In the equation above:

• $Bound_{lower}$ is the latency lower bound.

• $Bound_{upper}$ represents the latency upper bound.

For example, with the Google Search API, the search request latency should not exceed 100 ms; otherwise, the API does not meet business needs.

Well-defined SLOs allow users to set reasonable expectations. Without them, developers may assume performance levels that are at odds with the service design.

A good SLO specifies how it will be measured and the conditions under which it is valid. Examples:

• Response time for 95% of API calls < 500 ms

• The availabilityAll responses other than 5xx are used to calculate the availability of a service. We can also track 5xx responses to calculate a service's unavailability, then subtract that number from one to get the availability. of the API is 98%.

Choosing the right SLOs

SLO selection has direct product and business implications and requires oversight from both developers and business stakeholders:

• Keep it simple: Complicated SLIs and SLOs are harder to explain, understand, and implement.

• Use fewer SLOs: Only choose SLOs that provide meaningful coverage. If you cannot justify an SLO's priority, it will slow development.

• Avoid absolutes: We strive for "highly available," not "always available." The latter is unrealistic and sets unachievable expectations.

SLA

A service level agreement (SLA) is a contract that outlines the service's terms, conditions, availability, and performance guarantees. It defines the metrics and methods for measurement (uptime, response time, throughput, errors) and establishes remedies or consequences if objectives are not met. SLAs should prioritize customer experience to ensure satisfaction.