Design a Food Delivery API
You'll learn to
- -Give one shared order a state machine whose moves are authorized per actor
- -Run the machine, and see an illegal jump and a wrong actor each refused with the right code
- -Answer a nearby-restaurants request with a distance filter, and explain why a spatial index is needed at scale
A food delivery API is genuinely multi-sided. Three different actors, the customer, the restaurant and the driver, all work on the same order, each needing a different view and different real-time guarantees. That makes the prompt a good test of resource modeling under real complexity, not of one technique in isolation.
An Analogy: A Relay Race Baton
An order is a baton in a relay race. The restaurant hands it to the driver, and the driver hands it to the customer. Each runner may only take the baton at their own stage, in order. A runner cannot grab it early, and a stranger cannot grab it at all. The state machine below is the rule book for passing the baton.
Step 1-2: Three Actors, One Order Resource
The Order resource is shared. Each actor needs a different slice. The customer cares about status and estimated arrival. The restaurant cares about the items to prepare and a ready-for-pickup signal. The driver cares about pickup and drop-off locations and directions. This is a natural fit for the BFF pattern from the systems module: three tailored views of one underlying resource, instead of a single response that serves all three equally badly.
Step 3: A Multi-Actor Order State Machine
- -POST /v1/orders: the customer places an order.
- -GET /v1/orders/{id}: fetch an order, with the response shaped per actor by the BFF layer.
- -POST /v1/orders/{id}/transitions: the one endpoint every status change goes through, such as {"transition": "ready_for_pickup"}.
- -GET /v1/restaurants/{id}/orders?status=preparing: a restaurant's queue of active orders.
{
"id": "ord_501",
"status": "out_for_delivery",
"status_history": [
{"status": "placed", "at": "..."},
{"status": "confirmed_by_restaurant", "at": "..."},
{"status": "preparing", "at": "..."},
{"status": "ready_for_pickup", "at": "..."},
{"status": "picked_up", "at": "..."},
{"status": "out_for_delivery", "at": "..."}
]
}POST /v1/orders/ord_501/transitions
Authorization: Bearer <driver_token>
{"transition": "picked_up"}
HTTP/1.1 200 OK
{"id": "ord_501", "status": "picked_up"}
HTTP/1.1 403 Forbidden
{"error": "Only the assigned driver may transition this order to picked_up"}Each transition is made by a different actor. The restaurant confirms and marks ready. The driver marks picked up and delivered. So authorization has to be scoped per transition: only the assigned driver may mark picked_up, and only the restaurant may mark ready_for_pickup. That is the field-level authorization discipline from the GraphQL security chapter, applied to REST state transitions. Note there is one endpoint, not one per status. The legal-transition table, as in the state-machine chapter from the schema track, decides whether a move is allowed, not which URL was called.
Step 4: Geospatial Queries
GET /restaurants/nearby?lat=40.7128&lng=-74.0060&radius_km=5&cuisine=italian"Restaurants near me" is a special kind of filter. At scale it needs a spatial index, such as a geohash or an R-tree, because "distance from this point" is not something an ordinary B-tree index can answer efficiently. The demo runs the state machine and a simple nearby search. The search measures great-circle distance (the distance over the Earth's curved surface) and then filters by radius and cuisine, which is fine for five restaurants and not for five million. First the state machine.
Real-Time Driver Location
service TrackingService {
rpc WatchDriverLocation (WatchRequest) returns (stream LocationUpdate);
}This is server streaming from the gRPC modules, applied directly. The customer opens one stream and receives a continuous flow of location updates as the driver moves, instead of polling a REST endpoint over and over. It is the same live-feed reasoning as the GraphQL subscriptions chapter, expressed here as gRPC server streaming.
The strongest answers name which earlier technique each part of the design reuses: location search resembles the search and indexing chapters, the state machine mirrors the transition discipline from the schema track, and live tracking is server streaming. That is better than treating the prompt as a brand-new problem.
Interview Signal is part of Pro
See a real weak answer next to a real strong one for this exact topic.
Quiz is part of Pro
Test what you just read with a short quiz, and bank the XP.
Design a Food Delivery API in the API Design Lab's Full System Design act.
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!