Skip to content
API Design Learn/Capstone Case Studies
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Design a Food Delivery API

4 min read

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.
Order status as an explicit state machine, not a free-form string
{
  "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": "..."}
  ]
}
A status transition, scoped to whichever actor is allowed to make it
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

Finding nearby restaurants - a geospatial variant of the search/filtering chapters
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.

Press Run: a skipped step gets 409, the wrong driver gets 403, and the search applies a 5 km radius

Real-Time Driver Location

Server streaming for live location updates during delivery
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.

Ready to Build This?

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.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!