liveBook · Manning

Consistency

As explained in API Design Patterns

Data consistency is the property that related views or copies of data agree with one another and reflect an appropriate current state.

Data consistency means that related views or copies agree with one another and reflect an appropriate current state. API designs must make their consistency guarantees explicit because apparently obvious choices can have subtle consequences. section 2.3.3 section 2.3.5

Consistency problems often arise when separate clients update the same resource. Replacing an entire resource can overwrite unrelated changes, while field-targeted updates reduce that risk. Without checks or locking, the last replacement may silently erase an earlier update. section 8.1.2

Concurrent ChatRoom updates

Two clients read the same ChatRoom. One changes its title; the other changes its description. If both call ReplaceChatRoom with their complete, older representations, the second call can restore the first client's field to an old or null value. Partial updates avoid treating unrelated field changes as a conflict, while consistency checks may instead reject the stale replacement and require a retry. section 8.1.2

Choose a consistency strategy that matches the operation and its failure modes:

  • Treat list-valued fields as atomic values; exposing both whole-list replacement and individual-entry editing can create conflicting update paths. section 5.6.1
  • Copy data from a point-in-time snapshot or inside one transaction when the destination must represent one coherent state. section 17.3.6
  • If snapshots or transactions are unavailable, acknowledge that the copy may combine data from different times, or lock writes during the operation. section 17.3.6
  • Do not treat validation results for a later criteria-based deletion as guaranteed execution results; matching data may change between requests. section 19.3.5
  • Separate import and export from backup and restore: simple data movement provides no guarantees of atomic preservation or complete snapshot restoration. section 23.4
Table 8.1 An example sequence of code run by two users that could present problems (view table figure)

User 1 API call

User 2 API call

 
let chatRoom = GetChatRoom({
  id: '1'
});
 
let chatRoom = GetChatRoom({
  id: '1'
});
 
chatRoom.title = "My Chat!";
 
let desc = fetchRandomQuote();
 
chatRoom = ReplaceChatRoom({
  chatRoom: chatRoom,
});
 
chatRoom.description = desc;
 
 
chatRoom = ReplaceChatRoom({
  chatRoom: chatRoom,
});

Inspect the two-client request sequence to see how whole-resource replacement causes one client's unrelated change to disappear. section 8.1.2

Staleness is not always a defect. Request deduplication may deliberately return a cached response from an earlier attempt so retries produce the same result as the original request, even when the resource has since changed. section 26.3.3

How API Design Patterns covers it

How deep it goes
Explains overwrite scenarios, snapshots, locks, validation races, atomic list updates, and deliberately stale retry responses.
Examples
Uses concurrent ChatRoom replacements, copied resources, criteria-based deletion validation, list fields, imports, exports, and retried updates.
What you can do after
Evaluate consistency trade-offs and choose partial updates, snapshots, transactions, locks, or explicit staleness for each API operation.
How it connects
Connects consistency with partial updates, atomicity, transactions, snapshots, locking, request deduplication, and data loss.
Cover of API Design Patterns
liveBookmanning.com
Read API Design Patterns on liveBook Get the book at manning.com

Also explained in

Compare how 20 books explain consistency →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of API Design Patterns. The section links point to the parts of the book it draws on.