Entities and APIs

After gathering requirements, the next step is to identify the core entities in your system and design the APIs that allow users and services to interact with them. This foundational work shapes everything that follows.

Why Entities and APIs Come First

Before diving into architecture diagrams, you need to answer two fundamental questions:

• What data does the system manage? (Entities)
• How do users and services interact with that data? (APIs)

Getting this right makes the high-level design almost obvious. Getting it wrong leads to awkward architectures and confused interviewers.

Identifying Core Entities

Entities are the fundamental data objects your system manages. They emerge naturally from your requirements.

How to Identify Entities

1. Look at your functional requirements - Each major feature usually involves one or more entities
2. Identify the "things" users interact with - Posts, messages, orders, etc.
3. Consider relationships - How do entities relate to each other?

Example: Twitter/X

From the requirements (posting, following, viewing feed), we can identify:

Example: E-Commerce Platform

Level-Based Expectations: Entities

What interviewers expect varies significantly by level:

Designing APIs

Once you have entities, design the APIs that allow interaction with them. Focus on the most critical operations first.

API Design Principles

1. Start with CRUD - Create, Read, Update, Delete for each entity
2. Add domain-specific operations - Actions that span multiple entities
3. Think about pagination - Any list endpoint needs it at scale
4. Consider authentication - Who can call what?

RESTful API Example: Twitter

# User APIs
POST   /users                  # Create user (signup)
GET    /users/{id}             # Get user profile
PUT    /users/{id}             # Update profile
DELETE /users/{id}             # Delete account

# Tweet APIs
POST   /tweets                 # Create tweet
GET    /tweets/{id}            # Get single tweet
DELETE /tweets/{id}            # Delete tweet
GET    /users/{id}/tweets      # Get user's tweets (paginated)

# Follow APIs
POST   /users/{id}/follow      # Follow a user
DELETE /users/{id}/follow      # Unfollow a user
GET    /users/{id}/followers   # Get followers (paginated)
GET    /users/{id}/following   # Get following (paginated)

# Timeline API
GET    /timeline               # Get authenticated user's feed (paginated)

# Engagement APIs
POST   /tweets/{id}/like       # Like a tweet
DELETE /tweets/{id}/like       # Unlike a tweet

When to Use Different API Styles

Level-Based Expectations: APIs

Common API Design Mistakes

1. Forgetting Pagination

Every list endpoint needs pagination at scale. Without it, you'll timeout or OOM.

# Bad
GET /users/{id}/followers      # Returns all 10M followers

# Good
GET /users/{id}/followers?cursor=abc&limit=20

2. Not Thinking About Write Consistency

For important writes, consider idempotency keys:

# Without idempotency - double-charge risk
POST /payments  {amount: 100}

# With idempotency - safe to retry
POST /payments  {amount: 100, idempotency_key: "user123-order456"}

3. Exposing Internal IDs

Use opaque, non-sequential IDs for security:

# Bad - reveals information, easy to guess
GET /users/12345

# Better - opaque ID
GET /users/usr_a1b2c3d4e5

4. Ignoring Bulk Operations

At scale, you'll need batch endpoints:

# Inefficient - N API calls
GET /users/1
GET /users/2
GET /users/3

# Efficient - 1 API call
GET /users?ids=1,2,3
# or
POST /users/batch  {ids: [1, 2, 3]}

Putting It Together

Here's how to present entities and APIs in your interview:

You: "Based on our requirements, let me identify the core entities. For this Twitter-like system, we have Users, Tweets, and Follows as our primary entities. Users have profiles and credentials. Tweets have content, timestamps, and reference their author. Follows represent the relationship between users.

For our API, I'll focus on the critical paths. We need endpoints to create and read tweets, follow/unfollow users, and most importantly, fetch the timeline. The timeline endpoint will be our most called API and needs pagination with cursor-based navigation.

Should I sketch out the key API signatures, or shall we move to the high-level architecture?"

What's Next

With entities and APIs defined, you have a clear contract for what the system does. Next, we'll design the high-level architecture that makes it all work at scale.