How APIs Work — Farheen Shaikh

Every time you open an app and data appears — a tweet loads, a payment goes through, a recommendation pops up — an API made that happen. But "API" is one of those terms that gets thrown around so loosely it starts to mean nothing. Let's fix that.

01 What is an API?

API stands for Application Programming Interface. Strip the jargon: it's a contract between two pieces of software. One side says "here's how you can talk to me," and the other side follows those rules to get what it needs.

Think of it like ordering at a restaurant. You don't walk into the kitchen and cook your own food. You talk to a waiter — the interface — and the kitchen handles the rest. You don't need to know how the food gets made. You just need to know what's on the menu and how to order.

Your App ──── request ────→ API ──────────────→ Server / DB

Your App ←─── response ─── API ←───────────── Server / DB

The API sits between caller and system — translating, validating, responding.

In web development, APIs are almost always HTTP-based — meaning they use the same protocol your browser uses to load web pages. But how they use HTTP varies a lot. That's where REST, GraphQL, and RPC come in.

02 Select Between REST vs GraphQL vs RPC

In a system design interview — or a real project — you'll typically choose between three protocols. The right one depends on who is calling the API and what they need.

Protocol	Best for	Strength	Watch out for
REST	Client-facing web & mobile APIs	Simple, cacheable, maps to CRUD	Over/under-fetching with complex UIs
GraphQL	Flexible data-fetching clients	Clients request exactly what they need	Complex caching, harder to secure
RPC / gRPC	Internal microservice calls	Fast binary protocol, strong typing	Not human-readable, tighter coupling

✦ interview tip

Default to REST unless your interviewer signals otherwise. Mentioning "over-fetching" as a reason to consider GraphQL, or "internal microservices" as a reason to consider gRPC, shows architectural awareness without over-engineering.

03 REST — Resource Modeling

REST's core insight is simple: model your system as resources (things), not actions (verbs). Instead of createBooking(), you POST /bookings. Instead of getEvent(123), you GET /events/123.

Take Ticketmaster as an example. The core entities are events, venues, tickets, and bookings. These map directly to REST resources:

REST endpoints

GET  /events                   # list all events
GET  /events/{id}              # get a specific event
GET  /venues/{id}              # get a specific venue
GET  /events/{id}/tickets      # tickets for an event
POST /events/{id}/bookings    # create a new booking
GET  /bookings/{id}            # get a specific booking
      

Nested vs. flat resources

You have two options when resources relate to each other. Nest them when the relationship is required — you always need an event ID to get its tickets, so /events/{id}/tickets makes sense. Use query parameters when the filter is optional — /tickets?event_id=123§ion=VIP lets callers filter or not filter freely.

04 HTTP Methods — The Verbs Of REST

REST doesn't invent new verbs. It borrows from HTTP. Each method carries a specific meaning — and violating that meaning causes bugs that are very hard to track down.

Method	Does what	Idempotent?	Example
GET	Read data, change nothing	yes	`GET /events/123`
POST	Create a new resource	no	`POST /bookings`
PUT	Replace entire resource	yes	`PUT /users/42`
PATCH	Update part of a resource	sometimes	`PATCH /users/42`
DELETE	Remove a resource	yes	`DELETE /bookings/7`

✦ what "idempotent" means

Calling the same operation multiple times produces the same result. GET always returns the same data. DELETE leaves the resource gone whether you call it once or ten times. POST is not idempotent — hit it twice and you create two bookings.

05 Auth — who are you and what can you do?

Every real API has two layers of access control: authentication (who are you?) and authorization (what are you allowed to do?). Confusing them is one of the most common interview mistakes.

RBAC check flow

GET /bookings/{id}

Step 1 — Authentication
  Is the request carrying a valid JWT token?
  → 401 Unauthorized if not

Step 2 — Authorization (RBAC)
  Does this user own this booking?
  OR does this user have the admin role?
  → 403 Forbidden if neither

Step 3 — Return data
  → 200 OK with booking object
      

RBAC (Role-Based Access Control) assigns permissions to roles, then roles to users. In a Ticketmaster system:

customer — can book tickets, view their own bookings
venue_manager — can create events, view sales for their venues
admin — can access everything

06 Rate Limiting — Protecting Your API

Rate limiting prevents abuse by capping how many requests a client can make in a given window. Without it, a single bad actor can bring down your entire service.

common limits

Per-user        1000 requests / hour  # authenticated users
Per-IP          100  requests / hour  # unauthenticated
Per-endpoint    10   attempts / minute # e.g. booking, to stop scalpers

# When exceeded:
429 Too Many Requests
      

✦ interview tip

Mention rate limiting to show you think about production realities. A single sentence — "we'd implement rate limiting at the API gateway to prevent abuse" — is enough unless the interviewer digs further. Don't spend time on specific algorithms unless asked.

07 When To Select GraphQL

GraphQL solves a specific pain point: different clients need different data from the same endpoint. A mobile app showing a feed might only need title and thumbnail. A web dashboard might need the full event object plus venue details plus ticket availability.

With REST, you'd either create multiple endpoints (maintenance nightmare) or return everything and let the client discard what it doesn't need (wasted bandwidth). GraphQL lets each client ask for exactly what it needs in a single query.

GraphQL query

# Mobile app — minimal data needed
query {
  events {
    id
    title
    thumbnail
  }
}

# Web dashboard — full data needed
query {
  events {
    id
    title
    date
    venue { name city capacity }
    ticketsAvailable
    salesReport { total bySection }
  }
}
      

08 RPC For Internal Services

When two internal services need to talk — your user service checking permissions with your auth service, for example — REST's resource model can feel forced. You're not really dealing with a "resource" — you want to call a function remotely.

gRPC uses Protocol Buffers (binary, not JSON) and HTTP/2 for multiplexing. The result: lower latency, smaller payloads, and strong type contracts via a .proto schema file. The tradeoff: not human-readable, harder to debug in a browser.

gRPC vs REST for the same operation

# REST (resource-oriented, feels awkward)
GET /permission-checks?userId=42&resource=booking:7

# gRPC (action-oriented, natural)
checkPermission(userId: 42, resource: "booking:7")
→ returns: { allowed: true, role: "admin" }
      

09 API Design in Hurry

An API is a contract: "here's how you talk to me, here's what you get back."
REST is your default — resources as URLs, HTTP verbs as operations, JSON as the format.
GraphQL when clients need different shapes of data from the same source.
gRPC when internal services need high-performance, strongly-typed calls.
Always think about auth in two layers: authentication first, authorization second.
Rate limiting is not optional in production — mention it, even briefly.
Idempotency matters: GET and DELETE are safe to retry. POST is not.