Designing System Architecture with APIs

The Big Picture: High-Level Design (HLD)

The first step is to create a high-level design (HLD). Think of this as the architectural blueprint of your system. It's a "bird's-eye view" that shows the main components and how they communicate.

At this stage, your goal is to sketch a system that fulfills the core functional requirements. Resist the urge to dive into complex optimizations immediately. The first priority is to get a complete, working system on the whiteboard.

What Goes into a High-Level Design?

Your HLD diagram should be composed of standard building blocks. As an experienced engineer, you'll recognize these. The key in an interview is to select the right ones for the problem and draw them clearly.

A typical HLD will include components like:

• Clients (Mobile, Web)
• Content Delivery Network (CDN)
• Load Balancers
• API Gateway / Application Servers
• Databases (SQL, NoSQL)
• Cache Servers (e.g., Redis, Memcached)
• Message Queues (e.g., Kafka, RabbitMQ)
• Object Storage (e.g., S3)

Here are a couple of examples of what a finished HLD might look like.

Defining the Contract: API Design

Before you start drawing all those boxes and arrows, it's a best practice to first define your system's API. The API is the contract between the client and your system. Defining it upfront clarifies what the system needs to do and provides a clear guide for your HLD.

In an interview, you should aim to spend no more than 5 minutes on this step. The goal is a "good enough" API, not a perfect one.

Choosing an API Protocol

You'll need to choose a protocol for your API. While there are several options, the decision is usually straightforward.

• REST (Representational State Transfer): This is the industry standard for client-server APIs and should be your default choice. It's built on standard HTTP verbs (GET, POST, etc.) and uses URLs to represent resources.
• GraphQL: A good choice if you have diverse clients (e.g., mobile and web) with different data needs. It allows clients to request exactly the data they need, preventing over-fetching.
• RPC (Remote Procedure Call): Best suited for internal, high-performance communication between your microservices. It's more efficient than REST but less flexible for external clients.

Designing RESTful APIs

Since REST is the most common choice, let's focus on its core principles. A well-designed REST API is intuitive and predictable.

The key concepts are:

1. Resources: The "nouns" of your system (e.g., users, tweets, products). These should be plural and appear in the URL path.
2. HTTP Verbs: The "actions" you perform on resources (GET, POST, PUT, PATCH, DELETE).
3. Inputs: How you provide data to the API (path parameters, query parameters, request body).
4. Responses: How the API communicates back (status codes and a response body, usually JSON).

For example, designing an API for a simple Twitter-like service:

• Create a tweet: POST /tweets with the tweet text in the request body.
• Get a specific tweet: GET /tweets/{tweetId}
• Get a user's tweets: GET /users/{userId}/tweets
• Get the user's feed: GET /feed

Advanced API Topics: Authentication & Pagination

In a senior-level interview, simply defining the endpoints might not be enough. The interviewer might ask follow-up questions about security or handling large datasets.

• Authentication: Sensitive actions (like creating a tweet) must be authenticated. The user's identity should be derived from a secure token (e.g., a JWT or session token) passed in the request header, not from a userId field in the request body.
• Pagination: Endpoints that can return many items (like a user's list of followers) must be paginated.
  • Offset-based: Simple to implement (?page=2&limit=25). Can have issues with frequently changing data.
  • Cursor-based: More robust. Uses an identifier from the last item seen to fetch the next "page" (?cursor=last_item_id&limit=25).

Putting It All Together: From API to HLD

Now, let's connect the dots. The framework from Hello Interview suggests a clear path: identify core entities, define the API, and then build the HLD to support that API.

Let's walk through an example. Imagine we're designing Instagram.

1. Functional Requirements: Upload photos, view a news feed.

2. Core Entities: User, Photo, Follow.

3. API Design (REST):

   • POST /v1/photos - Upload a photo.
   • GET /v1/feed - Get the user's news feed.
   • POST /v1/users/{followed_user_id}/follow - Follow a user.

4. High-Level Design Diagram: We can now build the diagram by tracing each API call.

   • POST /v1/photos:
     • The client sends the request to a Load Balancer.
     • The LB forwards it to an Application Server (or a dedicated Media Service).
     • The server uploads the actual image file to Object Storage (like S3).
     • It then writes the photo's metadata (ID, caption, ownerID, object storage URL) to a Database (e.g., a SQL or NoSQL DB).
   • GET /v1/feed:
     • The client calls the feed endpoint.
     • The request goes to a Load Balancer, then to a Feed Service.
     • The Feed Service determines which users the current user follows (perhaps by querying a Follows table or service).
     • It then gathers the latest photo metadata for those users from a Database or a pre-computed Cache (like Redis).
     • The service returns a list of photo metadata, including URLs that point to a CDN for fast delivery.

This systematic process ensures your diagram directly addresses the system's requirements as defined by your API. You can find a similar example detailed in the "Design Instagram" section of the Igotanoffer article (LINK, section 2).

Conclusion

You've now learned how to bridge the gap between abstract requirements and a concrete architectural plan. This is a pivotal moment in any system design interview.

Key Takeaways:

• HLD is the Blueprint: It's a "bird's-eye view" of your system's major components and their interactions. Start simple and get a working system on the board first.
• API is the Contract: Define your API before drawing the HLD. It clarifies the system's responsibilities and guides your architectural choices.
• REST is Your Default: Use plural nouns for resources and standard HTTP verbs for actions. Be prepared to discuss pagination and authentication.
• Trace the Request: Build your HLD by tracing how each API endpoint is served by your components. This ensures your design is purposeful and directly solves the problem.

In our next lesson, we'll cover "Identify key areas for deep dive based on the problem and interviewer cues." Once your high-level design is on the whiteboard, the conversation will shift. You'll need to analyze your own design for potential bottlenecks, discuss trade-offs, and be ready to "zoom in" on specific components. This is where you demonstrate the depth of your technical expertise.