Predictability lets API users infer unfamiliar meanings and behavior from patterns they already understand. Consistent names and methods reduce research, prevent surprises, and make APIs faster to learn. section 1.4.4 section 7.0
Design for predictability with these practical rules:
- Use the same name for the same concept: call message content text everywhere rather than mixing text, inputText, and content. section 1.4.4 section 3.2.3
- Keep names general enough for legitimate future variation, but impose explicit language and syntax rules to prevent arbitrary alternatives. section 3.3
- Apply standard methods consistently across resources; define edge behavior, errors, and authorization semantics instead of leaving them ambiguous. section 7.0 section 7.2
One concept, one name
A message handler checks message.topic before calling PurgeTopic with messagingTopic. Because the two names appear to represent different concepts, users must stop and investigate instead of safely inferring their meaning. Renaming the request field to topic restores the expected pattern. section 3.2.3
Listing 3.1 Example frustrating code due to inconsistent naming
function handleMessage(message: Message): void { {
if (message.topic === "budget.purge") { #1
client.PurgeTopic({
messagingTopic: "budget.update" #2
});
}
}
Inspect the inconsistent topic and messagingTopic example to see how a small naming mismatch disrupts API reasoning. section 3.2.3
Predictability also depends on behavior, not only vocabulary. Standard Get, List, Create, Update, Delete, and Replace methods need shared semantics; otherwise identical actions become different puzzles on different resources. section 7.0 section 7.2
