suppose the API is
POST /account
and request body is
{Name: '',
type: '',
employment: '',
address : ''
}
now want to add phone_number as another attribute
can I make it backward compatible(minor version) by keeping this new attribute optional
OR its better to make a new version(major) so that existing clients are not impacted at all
As far as I can tell, the "rules" for backwards compatibility in REST are no different from in the broader category of messaging.
Assuming the semantics of the message are unchanged, and that there is a reasonable "default" interpretation of a missing optional field, then extending the message schema with a new optional value is going to be a lot easier then starting over.
You might look to HTTP itself for inspiration, in particular the design of headers. We can create new headers when it suits our purposes, with the security that components that are not familiar with our new semantics will ignore the unrecognized content.
In REST, forms are an interesting application of this idea; adding a new input control to an HTML form, with a sensible default value, is one way to offer an additional degree of control to a client that understands the new field without inhibiting the clients that don't know about it (provided, of course, those clients were designed to ignore unrecognized input controls).
A good reference on the evolution of messages: Greg Young's Versioning in an Event Sourced System.
