API Design

API design is a critical component of system design interviews, requiring candidates to define how clients interact with the system. While interviewers may not look for perfection, demonstrating the ability to design a reasonable, scalable API is essential. The process typically involves selecting a protocol, defining resources, and specifying data exchange methods.

The article outlines three primary API protocols: REST, GraphQL, and RPC. REST (Representational State Transfer) is the industry standard and default choice for most web services, using standard HTTP methods to manipulate resources. GraphQL is ideal for scenarios requiring flexible data fetching to avoid over/under-fetching, often relevant for complex frontend requirements. RPC (Remote Procedure Call), specifically gRPC, is best suited for high-performance internal service-to-service communication using binary serialization.

Beyond protocol selection, effective API design relies on solid resource modeling and understanding common patterns. For REST, this means identifying core entities (nouns) and defining relationships using path parameters for required hierarchies and query parameters for optional filtering. The article also highlights the importance of understanding HTTP methods—particularly the concept of idempotency—and the appropriate use of path parameters, query parameters, and request bodies for passing data.

Finally, the guide covers essential API patterns and security considerations that demonstrate production readiness. Pagination is crucial for handling large datasets, with cursor-based pagination being preferred over offset-based approaches for stability. Versioning strategies (URL vs. Header) allow APIs to evolve without breaking clients. Security fundamentals such as Authentication (identifying the user) and Authorization (permissions) are also discussed, comparing API Keys for service-to-service access against JWTs for user sessions, along with Rate Limiting to prevent abuse.

Key Concepts

• REST (Representational State Transfer): The default protocol for web services using standard HTTP methods (GET, POST, PUT, DELETE) to manipulate resources identified by URLs. Best for standard CRUD operations.
• GraphQL: A query language allowing clients to request exactly the data they need, solving over-fetching and under-fetching issues. Ideal for diverse clients with different data requirements.
• RPC (Remote Procedure Call): An action-oriented protocol (e.g., gRPC) using binary serialization for high-performance internal service communication.
• Idempotency: A property of certain HTTP methods (GET, PUT, DELETE) where making the same request multiple times produces the same result/state on the server. POST is generally not idempotent.
• Resource Modeling: The practice of mapping system entities to API resources (nouns, not verbs) and deciding how to represent relationships (nested URLs vs. query parameters).
• Pagination: Strategies for splitting large datasets. Offset-based is simple but fragile to data changes; Cursor-based uses a stable pointer and is better for large, dynamic datasets.
• Authentication vs. Authorization: Authentication verifies who the user is (e.g., via JWTs for users, API Keys for services), while Authorization determines what they are allowed to do.