API (Application Programming Interface)
API in Distributed systems is a set of rules and protocols that enable different software components, services, or systems to communicate with each other over a network.
API Design
- Synchronous API —> Returns only after the request has been fully processed.
- Asynchronous API —> Accept the request and return an operation ID for a background process that can be monitored via subsequent status requests.
RPC
What is RPC? gRPC Introduction.
👉 gRPC
IDL (Interface Definition language)
IDL is a formal way to describe an API’s structure, including its endpoints, request/response formats, and data types.
It allows automatic client code generation for multiple programming languages, reducing the need for manual API integration.
Example:
- OpenAPI (for REST APIs)
- Protocol Buffers (Protobuf) (for gRPC)
- Apache Thrift
- WSDL (for SOAP APIs)
Interface Description Language (IDL)
This is another term for IDL, emphasizing that it provides a structured way to describe API contracts. IDLs help automate API documentation, client SDK generation, and validation across different systems.
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users/{id}:
get:
summary: Get user by ID
responses:
"200":
description: User dataSLO (Service Level Objective)
An SLO (Service Level Objective) is a measurable performance target for an API or service. It defines expected levels of latency, reliability, and throughput to ensure quality of service.
- Latency (Response time) → e.g., 99% of requests complete within 200ms.
- Reliability (Availability) → e.g., API uptime is 99.99%.
- Throughput (Requests per second) → e.g., API supports 1,000 RPS.
Latency
measures the time taken to complete a request, typically in milliseconds. It should be representative of the user experience and attributable, meaning developers must identify its root cause to optimize performance.
Reliability
The fraction of successful requests out of total requests. In HTTP-based systems, measuring reliability requires careful consideration of response codes. 2xx codes indicate success, 5xx represent server failures, and 4xx can be ambiguous—some (like 404) may indicate client errors, while others (like 403) could signal service misconfigurations
Percentiles
Help measure system performance more accurately than averages, which can be distorted by outliers.
90th or 99th percentile latency provides a better understanding of user experience by showing the worst-case delays that impact a significant portion of users.
Idempotency
Ensures that an operation produces the same result regardless of how many times it is executed.
For example, setting X = 5 is idempotent, while X = X + 1 is not.
Idempotency simplifies error handling and retries in distributed systems, allowing operations to be safely reattempted without unintended side effects, improving system reliability.
Data Consistency
Ensures that replicated data across different data centers remains the same.
- Strong Consistency: Guarantees that once data is written, it is immediately visible and consistent across all locations before the write is considered complete.
- Eventual consistency: Allows the system to acknowledge the write after just one replica confirms it, and replication to other locations happens asynchronously in the background.
CAP Theorem
- Consistency (C): All replicas are in sync.
- Availability (A): Every request receives a response (success or failure).
- Partition Tolerance (P): The system can continue operating even if network partitions occur.
Orchestration & Kubernetes
Orchestration is the process of automating the deployment, management and scaling of distributed systems.
Kubernetes is the most widely used open-source orchestrator for managing containerized applications.
Health Checks
Health Checks are critical for ensuring that applications in a distributed system are functioning correctly and can be managed by an orchestrator.