PrepKitBeta
System Design›Foundations›API Design (REST, gRPC)

API Design (REST, gRPC)

Foundations

An API (Application Programming Interface) is a formal contract that defines how different software components should interact. In system design, the API is the public face of your service. A well-designed API is crucial for usability, scalability, and maintainability.

This chapter focuses on the most common API paradigms: REST and gRPC.

What Makes a Good API?

Before diving into specific technologies, let's define the qualities of a good API:

  • Easy to Understand and Use: It should be intuitive for developers to learn and use correctly.
  • Hard to Misuse: The design should guide developers away from making common errors.
  • Well-Documented: Clear documentation with examples is essential.
  • Stable and Reliable: It should be backward-compatible and not break existing clients without warning.
  • Secure: It must have proper authentication and authorization mechanisms.

REST: The Standard for Web APIs

REST (REpresentational State Transfer) is an architectural style, not a strict protocol. It uses the standard features of HTTP to create web APIs.

Core Principles of REST:

  1. Client-Server Architecture: The client and server are separate concerns.
  2. Statelessness: Each request from the client must contain all the information needed to understand and process it. The server does not store any client context between requests. This is key for scalability.
  3. Cacheability: Responses should be defined as cacheable or not, to improve performance.
  4. Uniform Interface: This is the most important principle and has four sub-constraints:
    • Resource-Based: APIs are designed around resources (e.g., /users, /tweets). You use standard HTTP methods (GET, POST, PUT, DELETE) to operate on these resources.
    • Manipulation of Resources Through Representations: The client receives a representation of the resource (e.g., a JSON object) and can modify it and send it back to the server.
    • Self-Descriptive Messages: Each response should include enough information for the client to understand it (e.g., using Content-Type headers to specify the format is application/json).
    • HATEOAS (Hypermedia as the Engine of Application State): The response should include links to other related actions or resources. For example, a response for a user might include a link to get all of their posts.

Example REST API Endpoint: GET /users/123/posts

  • Method: GET (Retrieve data)
  • Resource: The posts belonging to user 123.
  • Response: A JSON array of post objects.

Pros of REST:

  • Simplicity and Familiarity: It uses standard HTTP, which is well-understood by nearly all developers.
  • Human-Readable: JSON is easy to read and debug.
  • Broadly Supported: Every language and framework has excellent support for building and consuming REST APIs.
  • Statelessness: Makes it easy to scale horizontally.

Cons of REST:

  • Verbosity: JSON can be verbose, and HTTP headers add overhead.
  • Over-fetching and Under-fetching: A client might get more data than it needs (over-fetching) or have to make multiple requests to get all the data it needs (under-fetching).
  • No Formal Contract: There is no machine-readable way to define the API's contract. This is often solved with external tools like OpenAPI (Swagger).

gRPC: High-Performance Communication

gRPC (Google Remote Procedure Call) is a modern, high-performance framework for building APIs. It was developed by Google and is a popular choice for inter-service communication (i.e., microservices talking to each other).

Core Concepts of gRPC:

  1. Contract-First with Protocol Buffers (Protobuf): You define the API contract first in a .proto file. This file specifies the services, methods, and message formats.
    • Protocol Buffers are a language-agnostic, binary serialization format. They are much more compact and efficient to parse than JSON.
  2. Built on HTTP/2: gRPC leverages the features of HTTP/2, such as:
    • Multiplexing: Sending multiple requests and responses over a single TCP connection.
    • Server Push: The server can proactively push data to the client.
    • Streaming: gRPC supports bi-directional streaming, where both the client and server can send a stream of messages.
  3. Strongly Typed: The .proto file generates strongly-typed client and server code in your chosen language, reducing runtime errors.

Example gRPC .proto file:

syntax = "proto3";

service UserService {
  rpc GetUser(GetUserRequest) returns (User);
}

message GetUserRequest {
  string user_id = 1;
}

message User {
  string user_id = 1;
  string name = 2;
  string email = 3;
}

Pros of gRPC:

  • High Performance: The use of Protobuf and HTTP/2 makes it very fast and efficient, with low latency.
  • Streaming: Native support for streaming is a powerful feature for use cases like chat applications or live data feeds.
  • Strict Contract: The .proto file provides a single source of truth for the API, with strong typing.
  • Language Agnostic: Excellent support for many programming languages.

Cons of gRPC:

  • Limited Browser Support: Because it relies on HTTP/2 features, it's not as straightforward to call a gRPC service directly from a web browser as it is with REST. This often requires a proxy layer.
  • Not Human-Readable: The binary format is not readable by humans, which can make debugging more difficult.
  • Steeper Learning Curve: It's a more complex technology than REST.

REST vs. gRPC: When to Use Which?

This is a classic system design trade-off question.

  • Use REST for:

    • Public-facing APIs: Where broad compatibility and ease of use are important.
    • Simple request-response workflows.
    • When you need to support a wide range of clients, including web browsers.

  • Use gRPC for:

    • Internal microservice-to-microservice communication: Where performance and efficiency are critical.
    • Real-time applications that require streaming.
    • Polyglot environments where you need reliable communication between services written in different languages.

In many modern systems, you'll see a hybrid approach: gRPC for internal communication and a RESTful API gateway for external, public-facing traffic. This gives you the best of both worlds.

Back to Course