Reference Guide

// Execution phase
EasyMock.replay(switchServiceMock, jsonServiceMock);
String response = get(BASE_PATH);
// Verification phase
assertResponseContains(response, switchesJson);
EasyMock.verify(switchServiceMock, jsonServiceMock);
}
...
}
JSON Message Versioning
While there are no built-in constructs for JSON message versioning there are conventions
application developers can follow to ensure that multiple versions of a messages can be
exchanged via REST without causing unexpected errors. This can occur in particular during rolling
upgrades where different versions of an application may be active in a team of controllers.
Changing a message definition in JSON puts a burden on the sender and receiver of the
messages to deal with the new message formats. Three common ways to introduce versioning in to
JSON are:
1) Add New Fields (Ignore Unknown Fields)
When creating newer versions of a JSON message do not change existing fields but rather
add new fields as needed. Clients should parse just the fields they expect for their version of
the application and ignore new/unknown fields without error. In general, it is best if
applications ignore fields they do not expect or understand.
2) Version Message Field
A version field can be designated at the creation of the JSON message to represent the
message version ID. That version ID can be updated as the message changes with different
versions of the application. The receiver will then know through this field what message
format/content can be expected allowing it to adjust its parsing behavior. This is push
notification in that the sender is telling the receiver the version of the message sent.
3) Accept Header Version
The Accept Header of a HTTP request can indicate what message version(s) a receiver can
parse. This is a pull notification in that the receiver is telling the sender what message
versions the receiver is able to parse. This information may help the sending application
transmit message(s) in the correct format and avoid errors on the receiver.
189