liveBook · Manning

Stable identity

As explained in API Design Patterns

A stable identifier is an identifier whose association with an entity remains unchanged over the entity's relevant lifetime.

A stable identifier keeps the same association with an entity over its relevant lifetime. Array indexes usually fail this test: inserting an item or replacing an array can change which entity an index identifies. section 8.3.3

For individually addressable repeated-field items:

  • Do not retrieve or update an item by index; index-based access implies uniqueness and a stable ordering that the API may not guarantee. section 8.3.3
  • Use a map with stable local unique identifiers or expose items as sub-resources with global unique identifiers. section 8.3.3

An unstable administrator update

A ChatRoom containing administrators should not accept a PATCH that means “update the administrator at index 0.” The index can identify a different user after insertion or replacement. section 8.3.3

How API Design Patterns covers it

How deep it goes
Explains index instability and recommends maps or sub-resources, without detailing their implementation.
Examples
Uses ChatRoom administrators and an index-based PATCH request as concrete API examples.
What it assumes
Assumes basic familiarity with arrays and web API resource addressing.
What you can do after
Diagnose/debug with it by rejecting retrieval or updates addressed as “the item at index 0.”
How it connects
Connects stable identity to repeated fields, arrays, unique identifiers, map fields, and sub-resources.
Cover of API Design Patterns
liveBookmanning.com
Read API Design Patterns on liveBook Get the book at manning.com

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.