Accept
negotiation, no version parameter, and no implicit “latest” — every call
explicitly names the version it expects.
What “v1” means
Withinv1, MarketBox commits to backwards-compatible changes only.
Specifically, we may:
- Add new endpoints.
- Add new optional request fields.
- Add new response fields.
- Add new values to existing enums only when documented as open-ended.
- Add new error codes (treat unknown codes as the HTTP status implies).
- Relax validation that was previously stricter than necessary.
v1:
- Remove or rename fields.
- Change a field’s type or semantics.
- Add required request fields.
- Remove enum values.
- Change HTTP status codes for the same condition.
- Change the meaning of an existing error
code.
When we’d bump to v2
A v2 only ships when a change is genuinely incompatible — a rename
nobody can avoid, a semantic change to a core concept, or a restructure
that doesn’t fit under “additive.”
When a new major version ships:
/v1keeps working for an explicit, announced deprecation window.- Both versions run side by side during that window.
- Deprecation announcements include migration guidance per endpoint.
Forward-compatibility on your side
Help your integration weather additive changes:- Don’t fail on unknown response fields. Use a permissive JSON parser that ignores fields you don’t know about.
- Don’t fail on unknown enum values. Have a “unknown” branch in
your handling — don’t crash if a
statusshows up that your code hasn’t seen. - Don’t fail on unknown error codes. Fall back to handling by
HTTP status when you encounter a
codeyou don’t recognize. - Pin the version in your client. Make
/v1an explicit part of the URLs you generate, not a discoverable default.