Om's Brain

4. API Design

5 min read

1️⃣ Where API Design Fits in System Design Interview

Typical system design flow:

  1. Requirements
  2. Core entities
  3. API Design
  4. Data Flow
  5. High-Level Design
  6. Deep Dives

Interview Tip ⚠️

Do NOT spend too much time here. Ideal: ~5 mins max Why? API design is important, but not the main focus of system design interviews.

2️⃣ What is an API?

API = Application Programming Interface It allows 2 software systems to communicate using defined rules.

Example: Client → Server → Database

Browser → Backend → DB

Example: User opens Ticketmaster

GET /events

Flow:

  • Client asks backend for events
  • Backend asks DB
  • DB returns data
  • Backend returns response

In interviews, mostly focus on:

Client ↔ Backend APIs (external APIs) Not DB calls.

3️⃣ Protocols You Should Know

A) REST (Default Answer) ⭐

Use this 95% of time in interviews.

Why?

  • Simple
  • Standard HTTP
  • Easy to explain
  • Widely used

B) GraphQL

Use when client needs custom fields / nested data / avoid multiple calls

C) RPC / gRPC

Use for service-to-service communication

Mostly internal microservices.

D) Real-time Protocols

Mention only if needed:

  • WebSockets
  • SSE
  • WebRTC

Used for:

  • Chat apps
  • Live feeds
  • Streaming updates

4️⃣ REST API Design (Default Choice)

If confused in interview → choose REST.

REST is built on HTTP methods.

Resources = Core Entities

Your REST resources come from system nouns.

Example Ticketmaster:

  • Events
  • Venues
  • Tickets
  • Bookings

Resource Naming Rules

Always use:

✅ Plural nouns ❌ Verbs

Good:

GET /events
POST /events
GET /tickets
DELETE /events/123

Bad:

GET /getEvents
POST /createEvent
DELETE /removeEvent

Rule:

HTTP method = action URL = resource

5️⃣ HTTP Methods (Must Know)

MethodPurposeIdempotent?
GETFetch data✅
POSTCreate❌
PUTFull replace/update✅
PATCHPartial updateUsually
DELETERemove✅

Idempotent Meaning

Multiple same requests → same final state.

Example:

DELETE /events/10

Run 10 times → event still deleted.

Interview Tip

Mostly you’ll use:

  • GET
  • POST

Don’t overthink PUT vs PATCH unless asked.

6️⃣ Inputs to REST APIs

3 major input types.

A) Path Parameters

Used when resource is required.

Example:

GET /events/123

Need event ID.

Rule:

Required resource identifier → Path Param

B) Query Parameters

Optional filters.

Example:

GET /events?city=LA&date=2026-01-01

Used for:

  • Filtering
  • Sorting
  • Search
  • Pagination

Rule:

Optional filter → Query Param

C) Request Body

Used when sending data.

Mostly:

  • POST
  • PUT
  • PATCH

Example:

{
  "title": "Coldplay Concert",
  "location": "Mumbai",
  "date": "2026-07-10"
}

Rule:

Sending data → Body

7️⃣ API Response Design

2 parts.

A) Status Code

Tells success/failure.

B) Response Body

Usually JSON.

Common Status Codes

CodeMeaning
200Success
201Created
400Bad request
401Unauthorized
404Not found
500Server error

shortcut:

  • 2xx → Success
  • 4xx → Client issue
  • 5xx → Server issue

Interview Trick

Don’t waste time defining every field.

Instead:

Returns list of events
Returns booking object
Returns ticket details

High-level is enough.

8️⃣ GraphQL (When to Mention It)

Created by Facebook.

Used because REST can cause:

Over-fetching

Getting extra data not needed.

Under-fetching

Need multiple API calls.

REST Example:

GET /events/123
GET /venues/44
GET /tickets/9

Multiple requests.

GraphQL:

Single endpoint.

POST /graphql

Client asks exactly required fields.

Example:

event {
  name
  date
  venue {
    name
    address
  }
}

Benefits:

  • Flexible
  • Single request
  • Exact fields
  • Great for mobile/frontend

Use when:

  • Multiple frontend clients
  • Complex nested data
  • Custom field selection

9️⃣ GraphQL N+1 Problem

Classic follow-up question.

Problem:

Fetch 100 events Then fetch venue for each.

DB queries:

1 + 100 = 101 queries

Bad.

Solution:

  • Batching
  • DataLoader

Interview answer:

Use DataLoader / batch DB fetches.

🔟 RPC / gRPC (Internal Services)

Use for microservice-to-microservice communication.

Not usually client-facing.

Example:

Search service ↔ Ranking service Booking service ↔ Payment service

REST style:

GET /events/123

RPC style:

GetEvent(id)
CreateBooking()
GetAvailableTickets()

Looks like function calls.

Why gRPC is Faster

Uses:

  • Binary format (Protocol Buffers)
  • Strong typing
  • Less HTTP overhead
  • Smaller payload
  • Faster network transfer

Best for:

  • Internal microservices
  • Controlled systems

Why not for browser APIs?

Because REST is:

  • Human readable
  • Standard HTTP
  • Easier debugging
  • Works everywhere

1️⃣1️⃣ Pagination (Very Common Follow-up)

Needed when large datasets.

Bad:

GET /events

Returning 1M records ❌

Huge payload.

A) Offset/Page-Based Pagination

Simple.

GET /events?page=2&limit=25

Easy to implement.

Problem:

If heavy writes happen, data shifts.

May duplicate or skip records.

B) Cursor-Based Pagination

Better at scale.

GET /events?cursor=abc123

Cursor = last seen record.

Good for:

  • High write systems
  • Infinite scroll
  • Feeds

Interview answer:

Default = Page-based Heavy writes / consistency = Cursor-based

1️⃣2️⃣ Security (Very Common Follow-up)

Two things:

Authentication

Who are you?

Authorization

What can you access?

Example:

Yelp-like app:

  • View businesses → anyone
  • Post review → logged-in users
  • Create event → admins only

1️⃣3️⃣ JWT vs Session Token

JWT

Stored in HTTP header.

Authorization: Bearer <jwt>

Contains:

  • user id
  • role
  • expiry

Signed so client cannot modify.

Session Token

Header contains token only.

Server checks DB/cache for session info.

Key Interview Mistake ⚠️

Never trust user ID from request body.

Bad:

{
  "userId": 99,
  "tweet": "Hello"
}

Anyone could impersonate.

Correct:

User identity should come from:

  • JWT
  • Session token

Header-based auth.

1️⃣4️⃣ When There Is No External API

Some backend-heavy interviews:

Example:

Post indexing system Search infrastructure Ranking engine

No user-facing endpoint.

Then:

Either:

  • Skip API design
  • Or define internal service APIs

Check with interviewer.

Mindmap

Graph View