Negotiating a Shared API Contract

Delivery Scheduling is the order-fulfillment API behind this case study. Two consumer teams asked for different changes to the same endpoint /modify-delivery-date: the Web Storefront team needed more flexible pickup time slots, and the Mobile App team needed lighter responses to keep payloads small on mobile networks.

My call: ship a single endpoint with an additive (backward-compatible) contract — a flexible time_slots array plus a ?fields= query parameter for sparse fieldsets — instead of forking the endpoint per team. This console shows how it behaves.

Web Storefront — flexible time slots

The time_slots array accepts as many windows as the customer needs. Tick several at once.

09:00–10:3010:00–12:3017:00–18:00

POST /modify-delivery-date
{
  "order_id": "ORD-2026-88213",
  "time_slots": [
    {
      "start": "09:00",
      "end": "10:30"
    }
  ]
}

Mobile App — sparse fieldset

The ?fields= parameter trims the response down to the essentials. order_id is always returned.

GET /modify-delivery-date?fields=slots,eta
{
  "order_id": "ORD-2026-77410",
  "slots": [
    {
      "start": "10:00",
      "end": "12:30"
    }
  ],
  "eta": "2026-09-10T14:00:00Z"
}

Filtered response: 100 B
Full response: 256 B
Savings: 156 B (61%)

Sizes measured on the serialized JSON with no whitespace (UTF-8 bytes).