API Design

💻 API Overview and Context

An Application Programming Interface (API) is a general term for any programming interface used to access data or functionality. While simple interfaces (like a web browser’s local storage API or an object’s methods) technically count, the term is most commonly used to refer to an external service, typically an HTTP API.

The course focuses on three major paradigms for designing these external APIs:

REST (Representational State Transfer): The most popular and foundational model.
GraphQL: Introduced by Facebook to solve REST’s common issues like overfetching.
gRPC (Google Remote Procedure Call): A high-performance model designed for efficient service-to-service communication.

⚙️ REST APIs (Representational State Transfer)

REST is a set of loose restrictions or guidelines applied to HTTP APIs, not a protocol itself. Adhering to these guidelines creates standardized, recognizable, and scalable APIs.

Key Characteristics & Tradeoffs:

Characteristic	Description	Benefit/Drawback
Foundation	Built on top of HTTP, utilizing methods like GET, POST, PUT, DELETE, and standard HTTP status codes (e.g., 200, 404, 500).	Familiar and well-supported.
Statelessness	Requests must contain all necessary information; the server must not store any session-related state for the user between requests.	Big Benefit: Allows for horizontal scaling using load balancers, as any server can handle any request.
Resources	Endpoints are associated with a resource (a noun), like `/videos` or `/users`. The HTTP method provides the verb or action (e.g., `GET /videos` to retrieve, `POST /videos` to create).	Logical organization and easy to understand.
Data Format	Most commonly uses JSON (JavaScript Object Notation).	Benefit: Very human-readable and flexible.
State Management	Achieved through the client (browser cookies, session storage) and by sending state information within the request itself (e.g., pagination using query parameters like `limit` and `offset`).	Required for scalability but adds complexity to the client request.

🚀 GraphQL APIs

GraphQL is a query language for your API, built on top of HTTP (exclusively using POST requests to send a query in the body). It was created to address the issues of overfetching and underfetching common in REST.

Key Concepts & Tradeoffs:

Concept	Description	Tradeoff
Problem Solved: Overfetching	Clients can specify exactly which fields they need for any given resource in their query.	Benefit: Sends less unnecessary data over the network, improving performance.
Problem Solved: Underfetching	Clients can request data for multiple resources (e.g., a video, its comments, and the user for each comment) in a single request.	Benefit: Eliminates the need for multiple, consecutive requests (e.g., the “N+1 problem”).
Operations	Uses two main operations: Query (for read operations) and Mutation (for write/update/delete operations).	Clear separation of concerns.
Single Endpoint	Typically has just one endpoint (`/graphql`), handling all queries and mutations.	Streamlines API access.
Schema	Unlike the flexibility of JSON in REST, GraphQL is defined by a strict schema which dictates what resources and fields can be queried.	Drawback: POST requests (used exclusively) are not idempotent, making GraphQL requests harder to cache precisely than REST’s idempotent GET requests.

⚡ gRPC APIs (Google Remote Procedure Call)

gRPC is a modern, high-performance API framework created by Google. It is often used for server-to-server communication.

Key Characteristics & Tradeoffs:

Characteristic	Description	Benefit/Drawback
Foundation	Built on HTTP/2, which provides features like bi-directional streaming (similar to WebSockets) that can’t be achieved easily with standard HTTP/1.1 REST.	Drawback: Cannot be used natively from a browser without a proxy like gRPC-Web.
Data Format	Uses Protocol Buffers (protobufs) instead of JSON. Protobufs define a schema and serialize data into a binary format.	Massive Benefit: The binary format is smaller and faster over the network, leading to superior performance/efficiency compared to REST.
Paradigm	Adopts a Remote Procedure Call (RPC) style, where endpoints are treated as actions/functions (verbs), not just resources (nouns).	Developer experience is like calling a local function, making it feel very native in modern programming languages.
Schema Requirement	Protocol buffers require a strict, predefined schema (`.proto` file) for every request and response.	Drawback: Schemas add complexity to development and tooling, which is less mature than REST’s.
Status Codes	Does not typically use HTTP status codes (like 404/500) for error handling.	Drawback: Requires custom error handling based on defined error messages.

⚖️ Summary of Key Tradeoffs

Paradigm	Primary Benefit (The “Why”)	Primary Drawback (The Cost)
REST	Universal popularity, familiarity, easy browser use, great caching ability.	Prone to overfetching (getting too much data) and underfetching (requiring multiple requests).
GraphQL	Eliminates over- and underfetching by letting the client specify exactly what data is needed in a single request.	Not as good for caching as REST; only uses POST requests; adds a schema layer.
gRPC	Superior performance and efficiency due to binary data format (Protocol Buffers) and streaming capabilities (HTTP/2).	Difficult to use natively in a browser; requires specific tooling and a schema; less community support.