Versioning

Clients break when the shape changes under them

The PawWalk mobile app ships to the App Store and Play Store, gets installed on thousands of phones, and then sits there — unable to force an update the instant you change GET /walkers on the server. If you rename price_per_30_min_cents to rate_cents tomorrow, every app still running yesterday's code crashes or shows garbage. A public API is a promise, not just an implementation detail.

Versioning is how you keep that promise while still being able to change your mind. Freeze the CURRENT response shape behind a version marker, and when you need to break it, ship the new shape under a NEW version — old clients keep talking to the old version until they update.

Two common ways to mark the version: URL versioning (/v1/walkers, /v2/walkers — visible, cacheable, easy to route) and Accept-header versioning (Accept: application/vnd.pawwalk.v1+json — one clean URL, but harder to test in a browser and easy for a client to forget to set). Most public APIs (Stripe, GitHub) pick URL versioning for exactly that visibility — you can see which version a request hit just by reading the path.