Designing API Contracts with REST and RPC

Hello! Welcome back to your system design course.

In our last lesson, we delved into the fundamental trade-offs of distributed systems—Consistency, Availability, Latency, and Scalability. We established that you can't have everything at once and that designing a system involves making deliberate choices based on your application's needs. We discussed that these systems are composed of different services that need to communicate and coordinate.

Today, we'll focus on exactly how that communication happens.

Today's Goal

This lesson will teach you how to design API contracts for system components using REST or RPC patterns.

An API (Application Programming Interface) is the mechanism through which different software components interact. The "contract" is the formal agreement that defines the rules of that interaction.

Coming from a product design background, you can think of an API contract as a detailed technical specification for a part in a larger assembly. For a product to work, every component must adhere to its specifications—its dimensions, material, and connection points. An API contract serves the same purpose for software components, ensuring they can connect and work together seamlessly.

---

1. What is an API Contract?

An API contract is a formal, written agreement that specifies how a client should interact with a server or how two services should communicate with each other. It provides a single source of truth that development teams can rely on.

To understand why this is so important, let's look at a resource that breaks down the key components and benefits.

As the article highlights, a well-defined contract includes endpoints, methods, request/response formats, and authentication rules. This clarity prevents misunderstandings and allows frontend and backend teams to work independently.

Now, let's explore the two most common patterns for structuring these contracts: REST and RPC.

---

2. REST: The Language of the Web

REST (Representational State Transfer) is an architectural style that has become the de facto standard for building web APIs, especially for public-facing services and client-server communication (e.g., a mobile app talking to a backend).

REST is built on the principles of the web itself. It uses standard HTTP methods to perform actions on "resources."

To get a comprehensive overview, let's watch a video that explains API design from an interview perspective. It provides a clear, practical breakdown of REST.

Key Elements of a REST API Contract

As the video explained, designing a REST API involves defining the following:

• Resources: The "nouns" of your system. These are typically plural (e.g., /users, /products, /orders).
• Endpoints: The specific URL that identifies a resource (e.g., /products/12345).
• HTTP Methods: The "verbs" that define the action to be taken on a resource.
  • GET: Retrieve a resource.
  • POST: Create a new resource.
  • PUT / PATCH: Update an existing resource (fully or partially).
  • DELETE: Remove a resource.
• Request/Response: The data formats for communication. This includes path parameters, query parameters, request bodies, and the structure of the JSON response.
• Status Codes: Standard codes to indicate the outcome (e.g., 200 OK, 201 Created, 404 Not Found, 500 Internal Server Error).

This entire process can be visualized as a clear, four-step design flow.

Example: A Simple Blogging API

Let's say we're designing an API for a blog. Here’s what a simple REST contract might look like:

• Create a new post: POST /posts
  • Request Body: { "title": "My First Post", "content": "Hello, world!" }
  • Response: 201 Created with the full post object, including its new ID.
• Get all posts: GET /posts
  • Response: 200 OK with a list of post objects.
• Get a single post: GET /posts/{postId}
  • Response: 200 OK with the full post object.
• Delete a post: DELETE /posts/{postId}
  • Response: 204 No Content (indicating success with no data returned).

This structure is intuitive and leverages the built-in features of HTTP, which is why it's so popular.

---

3. RPC: For High-Performance Internal Communication

While REST is great for public APIs, it's not always the best choice for communication between services inside a complex, distributed system (i.e., microservices). For this, we often turn to RPC (Remote Procedure Call).

The core idea of RPC is simple: make a function call on a remote server as if it were a local function in your own code. Instead of thinking about resources and HTTP verbs, you think about actions and methods.

Modern RPC frameworks like gRPC (developed by Google) are designed for high performance. They use efficient, binary data formats instead of human-readable text like JSON, and they operate over the high-performance HTTP/2 protocol.

Let's watch a short video that explains gRPC and its benefits.

Key Elements of a gRPC API Contract

With gRPC, the contract is formally defined in a .proto file using Protocol Buffers. This file specifies:

1. Services: A collection of related functions (e.g., TicketService).
2. Methods: The specific functions that can be called (e.g., GetEvent, CreateBooking).
3. Messages: The data structures for requests and responses (e.g., GetEventRequest, Event).

From this single .proto file, gRPC can automatically generate the client and server code in many different programming languages, ensuring the contract is strictly followed.

Example: RPC vs. REST

Let's see how a simple action compares in REST and RPC.

Action	REST	RPC (Conceptual)
Get user details	GET /users/123	usersService.getUser({ userId: 123 })
Add a product	POST /products	productsService.addProduct({ name: "...", price: ... })

The RPC vs REST article from AWS provides a great table illustrating this difference. The RPC approach feels more like programming, while the REST approach feels more like manipulating data records.

---

4. Choosing the Right Pattern

So, when should you use REST versus RPC?

• Use REST for:

  • Public/External APIs: It's a web standard that any developer can easily understand and use without special tooling.
  • Client-to-Server Communication: Perfect for web and mobile apps talking to your backend.
  • Resource-centric services: When your API is primarily about CRUD (Create, Read, Update, Delete) operations on data objects.

• Use RPC (like gRPC) for:

  • Internal Microservice Communication: When you control both the client and the server, and performance is critical.
  • Action-oriented services: When the API is more about triggering actions than managing data objects (e.g., paymentService.processPayment(...)).
  • Polyglot environments: When your microservices are written in different languages, gRPC's code generation is a huge benefit.

---

Conclusion

Today we've demystified API contracts and explored the two dominant patterns for designing them. You now have a framework for defining how the different parts of your system will communicate.

Key Takeaways:

• API contracts are the blueprints for communication in a distributed system, enabling clarity and parallel development.
• REST is a resource-oriented style using standard HTTP verbs. It's the default choice for public APIs and client-server interaction due to its simplicity and ubiquity.
• RPC is a function-oriented style focused on executing actions. Modern implementations like gRPC are optimized for high-performance, internal communication between microservices.
• The choice between REST and RPC is a classic design trade-off between standardization/simplicity (REST) and performance/type-safety (gRPC).

Preview of the Next Lesson:

We've now covered architectural patterns, fundamental trade-offs, and communication contracts. The final piece of the fundamentals puzzle is learning how to represent all of this visually. In the next lesson, we will learn how to create component diagrams that effectively communicate system architecture. This will allow you to take all the concepts we've discussed and present them in a clear, easy-to-understand blueprint.