The API Design Interview Framework
You'll learn to
- -Follow a repeatable five-step process for any API design prompt: clients, resources, protocol, contract, evolution
- -Define a resource and tell it apart from an action
- -Walk a ride-sharing prompt through all five steps, including a real request and response
- -Avoid the most common failure: designing endpoints before knowing who calls them
Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.
The prompt "design an API for a ride-sharing app" is deliberately broad, and how you narrow it down matters more than the first endpoint you write. Just as with the LLD framework from ScaleDojo's LLD Fundamentals course, API design interviews reward a repeatable process over improvisation. Five steps cover almost any prompt.
An Analogy: Designing a Restaurant Menu
A good menu is not a list of whatever the kitchen can cook. The owner first works out who the guests are: families, office workers, or people in a hurry. Then the dishes are grouped into sections, a way of ordering is chosen (waiter, phone or app), each item is described with a price, and the owner plans how to change the menu in spring without confusing regulars.
- -Knowing the guests is clarifying the clients: who calls this API, and for what.
- -Grouping dishes into sections is modeling resources.
- -Choosing how orders are taken is choosing the protocol.
- -Describing each item and its price is designing the contract.
- -Planning the spring menu is planning how the API evolves without breaking existing users.
The Five Steps
- -Clarify use cases and clients. A mobile app, a partner integration and an internal service all want different things from the same data.
- -Model the resources (or, for GraphQL, the schema's types). A resource is a noun the API exposes: something with its own identity, such as a ride or a driver, reachable at its own address like /rides/812. Actions such as "cancel" are things you do to a resource, not resources themselves.
- -Choose the protocol: REST, GraphQL or gRPC, justified by the clients and access patterns from step 1 and not by habit.
- -Design the contract: endpoints or methods, request and response shapes, status codes or error types, and who is allowed to call what.
- -Discuss evolution. How does the API change without breaking existing clients? Versioning, deprecation and backward-compatible additions.
A Worked Example: Ride-Sharing
- -Step 1, clients. A rider app needs the driver's ETA. A driver app needs the pickup point and a way to accept a ride. An internal billing service needs the final fare, once, when the ride is complete. Three clients, three different views of one ride.
- -Step 2, resources. The nouns are rides, drivers, riders and payments. A ride has a lifecycle: requested, accepted, driver arriving, in progress, completed, or canceled.
- -Step 3, protocol. REST fits rides and payments: simple and cacheable. Live driver location needs a push channel such as a WebSocket or a streaming gRPC call. The internal billing service can use gRPC, since both sides are ours and speed matters.
- -Step 4, contract. Requesting a ride is a POST to the rides collection. The server answers 201 Created with the new ride's address. A rider who already has an active ride gets 409 Conflict, and a missing pickup point gets 422 Unprocessable Entity, with a clear error body.
- -Step 5, evolution. Adding a field such as surge_multiplier to the response is safe, because old clients ignore what they do not know. Renaming a field is not safe, and needs a new version and a deprecation period.
POST /rides HTTP/1.1
Content-Type: application/json
{ "pickup": { "lat": 51.5007, "lng": -0.1246 }, "dropoff_address": "10 Downing Street" }
HTTP/1.1 201 Created
Location: /rides/812
{ "id": 812, "status": "requested" }The Failure Mode: Endpoints Before Requirements
The most common way candidates lose points is sketching GET /rides, POST /rides and GET /rides/{id} within the first two minutes, before establishing who calls the API and what a ride needs to contain for each caller. A driver-facing client needs different fields and different real-time guarantees from a rider-facing client or the billing service. Designing the shape first leads either to one overloaded, kitchen-sink resource or to a redesign halfway through the interview.
Watch for the same failure in reverse: clarifying for so long that you never design anything. Spend two to three minutes on questions, then move. The goal is enough context to make defensible decisions, not exhaustive certainty.
You're asked to "design an API for a food delivery app." What is your first move?
"I'd start with a Restaurant resource and a MenuItem resource, then build out CRUD endpoints for each."
"Before modeling anything, I want to know who's calling this - is this the customer-facing app, the restaurant's order-management dashboard, or the delivery driver's app? Each of those wants a different shape of the same underlying data, and possibly a different protocol - the driver app might need a real-time subscription for new orders, while the restaurant dashboard is fine with plain polling. That's what determines whether I'm designing one API or three."
What is the first step in the API design interview framework?
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!