Introduction to APIs in System Design

What is an API?

An API (Application Programming Interface) is a contract that defines how two software components communicate. It hides implementation details and exposes only what is necessary for interaction.

Think of it as menu in a restaurant:

• The menu (API) lists available dishes (functions/endpoints).
• The kitchen (implementation) prepares the dish, but the customer (client) doesn't see how it's made.

APIs ensure standardized communication between clients, services, and systems.

An API is the “bridge” that allows two different components (which could be applications, services, or systems) to talk to each other in a standardized way.

OR

A contract between a producer (server/service) and a consumer (client/another service)

Example 1: Client <-> Server

Suppose a mobile app (client) sends GET /users/123 to a backend API.

The server responds with user details in JSON.

They don't care about each other's internal implementation – they only care about the API contract.

Importance of APIs in System Design

APIs are not just code-level utilities – they are the backbone of communication in modern software systems. Their importance spans technical, business, and developer experience aspects.

1 Separation of Concerns & Abstraction (decouple)

• APIs hides implementation details and exposes only what consumers need.
• Example: A “User API” exposes /users/{id} -> you don't are if the user data comes from MySQL, MongoDB, or an external provider.

This makes systems modular and easier to evolve.

2 Interoperability Between Components

• APIs allow different systems, built with different technologies, to communicate.
• Example: A Java service calls a Python microservice via REST or gRPC.
• APIs act as a common language between heterogenous systems.

Enables polyglot architectures.

3 Scalability & Flexibility

• APIs allow you ton scale parts of a system independently.
• Example: In e-commerce, you might scale the Order API differently than the Inventory API.
• API Gateways help route, throttle, and load-balance traffic.

Helps built cloud-native, elastic systems.

4 Ecosystem and Integration

• APIs are how organizations exposes functionality externally.
• Example: Stripe's Payment API, Google Maps API, Twitter API.
• They enable partnerships, third-party integrations, and even entire ecosystems.

APIs = new business models (API economy)

5 Security and Control

• APIs act as entry points into a system.
• With authentication (OAuth2, JWT) and authorization (RBAC, scopes), APIs ensure only authorized clients access resources.
• Rate-limiting and monitoring help prevent abuse.

APIs = controlled and secure access

6 Developer Experience (DX)

• APIs are how developers consume your system.
• A well-designed API = easy adoption, fewer errors, faster innovation.
• A poorly designed API = frustration, bugs, and abandonment.

APIs = the “UI” for developers.

7 Maintainability & Evolution

• Since APIs are contracts, teams can evolve internal implementations without breaking clients.
• Versioning strategies (/v1/, /v2/) allow smooth upgrades.

Ensures long-term sustainability of systems.

8 Independent Development

• Teams can work in parallel:
  • Frontend team builds against the API spec (mock responses).
  • Backend team builds the actual service.
• As long as the API contract remains stable, both sides are decoupled.

Example of Decoupling with API

Without API:

• Frontend directly queries the database -> tightly coupled.
• Changing DB schema = breaks frontend.

[Frontend]  --->  [Database]
   |                 |
   |   Direct SQL    | 
   |   queries       |
   |                 |
Changes in DB schema = Frontend breaks

With API:

• Frontend calls /api/v1/users/123.
• Backend handles DB changes internally.
• Frontend remains unaffected as long as API response format is consistent.

[Frontend]  --->  [API Layer]  --->  [Database]
   |                 |                 |
   |   Calls API     |   Handles DB    |
   |   (GET /users)  |   changes       |
   |                 |                 |
Changes in DB schema ≠ Breaks frontend

Thus APIs decouple clients from servers, and services from each other. This loose coupling is what makes modern architectures (like microservices, serverless cloud-native) possible.

Types of APIs

APIs differ by who uses them, how they communicate, and what role they play in the system.

1 Based on Accessibility (Who Can Use Them)

• Internal APIs
  • Used only within an organization.
  • Example: Order Service calling Payment Service in a microservice system.
  • Benefit: Teams can work independently, but API is not exposed outside.
• Partner APIs
  • Shared with trusted business partners.
  • Example: A logistics provider exposing shipment tracking API to e-commerce partners.
  • Benefit: Enable B2B integrations.
• Public / Open APIs
  • Available to external developers and the public.
  • Example: Twitter API, Google Maps API, OpenWeather API.
  • Benefit: Builds ecosystems, increases adoption.
• Private APIs
  • Used between internal microservices. Still requires strong contracts, but versioning can be more flexible.

2 Based on Communication Style

• REST (Representational State Transfer)
  • Stateless, Cache friendly
  • Resource-based (/users/123)
  • Uses HTTP methods (GET, POST, PUT, PATCH, DELETE).
  • It uses JSON format as response.
  • Widely used, simple to adopt.
• GraphQL
  • Query language for APIs.
  • Clients specify exactly what data they need.
  • Instead of exposing multiple endpoint like in REST, it exposes single endpoint (/graphql).
• gRPC (Google Remote Procedure Call)
  • High-performance, uses Protocol Buffers (binary format).
  • Great for internal microservice communication.
• SOAP (Simple Object Access Protocol) (Legacy)
  • XML-based, older but still used in banking, enterprise systems.
  • It uses XML.
  • Heavy but standardized.
• WebSockets / Streaming APIs
  • Real-time, bidirectional communication.
  • Example: Chat application, live stock prices.
• Event-driven APIs (Webhooks, Pub/Sub)
  • Push updates to clients when event occur.
  • Example; Stripe webhook for “payment succeeded.”.

Which Style to Use:

                           ┌────────────────────┐
                           │   Incoming API     │
                           └──────────┬─────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    │                                   │
           ✅ Client-Facing                        ✅ Internal RPC
        (Web / Mobile / Public)                    (Microservices)
                    │                                   │
       ┌────────────┴────────────┐               ┌──────┴───────┐
       │                         │               │              │
Over/Under Fetching?     NOT a concern    High-QPS / Low Lat?   NO
       │                         │               │              │
    ✅ YES                     ✅ NO           ✅ YES         ✅ NO
       │                         │               │              │
   ✅ GraphQL                 ✅ REST          ✅ gRPC        ✅ REST

3 Based on Usage in System Design

• External APIs – For customer, partners, third-party developers.
• Internal APIs – For microservice-to-microservice communication.
• Composite APIs – Combine multiple APIs into one (useful for API Gateways or BFF – Backend for Frontend).
• Library APIs – Exposed within software libraries/SDKs for developers.

API Types Comparison

Role of APIs in Distributed Systems

In a distributed, service-oriented or microservice architecture:

• APIs serve as the communication bridge between independent services.
• They enforce loose coupling – services can evolve independently as long as the API contract remains consistent.
• APIs allow scaling different parts of a system independently (e.g., scaling the user-service without touching the payment-service).

Example:

• A mobile app calls the API Gateway.
• The Gateway routes the requests to User Service (user data) or Payment Service (transactions).
• The client only sees the API – not the underlying complexity.