We have the concept of versioning on the transport wire format which allows us to make changes to the product whilst maintaining backwards compatibility with nodes on previous versions (but still on the same major version). We currently have no such versioning for the REST request/response format. For the request format we tend to add backward compatibility support in the Parsers to parse the old parameters as well as the new ones (these tend to be jumbled together with the new parameters with no clear indication they are deprecated formats still there for bwc), but for the REST Response format we don't have any way of knowing what version of the format the client expects so cannot maintain bwc with changes.

We could add a query parameter to every REST action called format whose value would specify which version the server should expect for request formats and which version the client expects for response formats. This would allow us to have the same kind of bwc logic that we have for the transport layer (if the format parameter is missing then it will default of the server's version or possibly to trying all available formats).

We could then also have a new API which would return the XContentTypes and format versions supported by the server. Clients could then use this API to determine whether they are compatible with the server on client initialisation and work out which version they need to specify in the format parameter.

This would be a big and long term change and certainly would not happen overnight as we would have to slowly introduce the bwc code in the XContent parsers and renderers.