A semantic change alters an API’s behavior or the meaning of its resources and fields. It may be obvious, such as a new permission model, or subtle, such as changing list or array ordering. Even an improvement can be backward incompatible when users depend on stable results. section 24.2.2
Chat message policy
A Chat API might add a message policy that blocks messages sent faster than once per second or rejects abusive content detected by machine learning. Existing calls to sendMessage can then fail, while code that expects two messages may fail later when it checks listMessages. Assess the disruption and users’ tolerance for instability before changing an existing version or isolating the behavior in a new one. section 24.2.2
Listing 24.3 Code that may fail after new semantic changes introduced
function testMessageSending() {
const chatRoom = GetChatRoom.get(1234);
chatRoom.sendMessage("Hello!"); #1
chatRoom.sendMessage("How is everyone?"); #2
}
Shows message-sending calls that may fail after a semantic change. section 24.2.2
Listing 24.4 Code that may fail in a different place after changes
function testMessageSending() {
const chatRoom = GetChatRoom.get(1234);
chatRoom.sendMessage("Hello!"); #1
chatRoom.sendMessage("How is everyone?"); #1
const messages = chatRoom.listMessages();
if (messages.length != 2) { #2
throw new Error("Test failed!");
}
}
Shows a failure surfacing later when code validates returned messages. section 24.2.2
