API Design

📖 2 min read 📄 Part 5 of 10

API Design for Food Delivery Service

REST APIs

Customer APIs

POST /api/v1/restaurants/search
{
  "location": {"lat": 37.7749, "lon": -122.4194},
  "cuisine": "italian",
  "radius_km": 5
}

Response 200:
{
  "restaurants": [{
    "id": "rest_123",
    "name": "Pizza Palace",
    "rating": 4.5,
    "delivery_time": "30-40 min",
    "delivery_fee": 2.99
  }]
}

POST /api/v1/orders
{
  "restaurant_id": "rest_123",
  "items": [{"item_id": "item_456", "quantity": 2}],
  "delivery_address": "123 Main St",
  "payment_method_id": "pm_789"
}

Response 201:
{
  "order_id": "ord_abc",
  "status": "PENDING",
  "total": 45.99,
  "estimated_delivery": "2024-01-08T13:30:00Z"
}

GET /api/v1/orders/{order_id}/track
Response 200:
{
  "status": "IN_TRANSIT",
  "driver": {"name": "John", "rating": 4.8},
  "location": {"lat": 37.7749, "lon": -122.4194},
  "eta": "2024-01-08T13:25:00Z"
}

Driver APIs

POST /api/v1/drivers/status
{"status": "available"}

GET /api/v1/drivers/delivery-requests
Response 200:
{
  "requests": [{
    "order_id": "ord_abc",
    "restaurant": "Pizza Palace",
    "pickup_location": {"lat": 37.7749, "lon": -122.4194},
    "delivery_location": {"lat": 37.7849, "lon": -122.4294},
    "estimated_distance_km": 3.5,
    "payout": 8.50
  }]
}

POST /api/v1/drivers/accept-delivery
{"order_id": "ord_abc"}

POST /api/v1/drivers/location
{"lat": 37.7749, "lon": -122.4194}

Restaurant APIs

GET /api/v1/restaurants/orders
Response 200:
{
  "orders": [{
    "order_id": "ord_abc",
    "items": [{"name": "Pizza", "quantity": 2}],
    "status": "PENDING",
    "created_at": "2024-01-08T12:00:00Z"
  }]
}

POST /api/v1/restaurants/orders/{order_id}/accept
{"prep_time_minutes": 20}

PUT /api/v1/restaurants/menu/{item_id}
{"is_available": false}

WebSocket APIs

// Customer tracking
ws://api.example.com/ws/orders/{order_id}

Messages:
{
  "type": "location_update",
  "driver_location": {"lat": 37.7749, "lon": -122.4194},
  "eta": "2024-01-08T13:25:00Z"
}

{
  "type": "status_update",
  "status": "PICKED_UP",
  "message": "Driver picked up your order"
}

// Driver updates
ws://api.example.com/ws/drivers/{driver_id}

Messages:
{
  "type": "new_delivery_request",
  "order_id": "ord_abc",
  "restaurant": "Pizza Palace"
}

SDK Example

from food_delivery_sdk import FoodDeliveryClient

client = FoodDeliveryClient(api_key="key_123")

# Search restaurants
restaurants = client.restaurants.search(
    location=(37.7749, -122.4194),
    cuisine="italian"
)

# Place order
order = client.orders.create(
    restaurant_id="rest_123",
    items=[{"item_id": "item_456", "quantity": 2}],
    delivery_address="123 Main St"
)

# Track order
tracking = client.orders.track(order.id)
print(f"Driver location: {tracking.driver_location}")
print(f"ETA: {tracking.eta}")

This API design provides comprehensive interfaces for all platform actors. The next documents will cover scaling, tradeoffs, variations, security, and interview tips.