Content negotiation and versioning

Plan for the second version before shipping the first

Removing a field, renaming one, tightening validation, or changing a status code are all breaking. Adding an optional field is not — provided clients ignore unknown fields, which you should state explicitly.

A version in the path is the most obvious and most widely understood option. Header-based versioning is tidier and harder for people to use with a browser or a curl command.

Whatever you choose, publish a deprecation policy and honour it. An API that changes without notice is one people build defensive wrappers around.