user
~22 tokens
What's the best way to version a Phoenix JSON API? URL path vs header vs query param?
assistant
~140 tokens
For most projects, **URL path versioning** is the pragmatic choice. Explicit and discoverable — you can see the version in logs, docs, curl commands. Easy to route in Phoenix. Cacheable by CDNs.
**Key principle:** Don't version prematurely. Start with `/api/conversations` (unversioned). Add `/api/v1/` prefix only when you need a breaking change. Most APIs never need v2.
For Bump specifically: you're self-hosted with a small consumer surface. Keep it unversioned until you have a concrete reason to version.
user
~22 tokens
What about when I do need to make a breaking change? How do I manage two versions simultaneously?
assistant
~120 tokens
The cleanest Phoenix pattern is **shared context, separate views**:
1. **Keep one context module** — the business logic doesn't change
2. **Separate controller views** — V1 and V2 render different JSON shapes
3. **Version-specific controllers only when logic differs**
**Deprecation strategy:** Add `Deprecation: true` response header to V1. Log V1 usage. Set a sunset date. Remove after 6+ months with zero traffic.