Integration Design Guide#

This page ties together the behavior described elsewhere in the guide and turns it into practical rules of thumb for long-running integrations.

Integration Cost Model#

Cheap Operations#

These are usually in-memory:

  • Reading fields on objects you already loaded.

  • Reusing materialized children and entries collections.

  • Matching IDs inside collections you already fetched.

Expensive Operations#

These usually trigger remote work:

  • First access to lazy collections such as children and entries.

  • Calling refresh() and then reading the same objects again.

  • Broad tree traversal or repeated full enumeration.

  • Explicit low-level calls through user.api_get and user.api_post.

Design Guidelines#

  • Prefer ID-first state in your integration model. Names and paths are best treated as discovery and presentation data.

  • Keep traversal bounded by scope and depth, and favor incremental scans over full rescans.

  • Place refresh() at synchronization boundaries where outside mutation is plausible.

  • After refresh(), reacquire child objects from the refreshed parent before trusting child fields.

  • After failures, re-resolve from a stable anchor such as a known parent plus stored ID metadata.

Suggested Reading Order#

  1. Accessing Items with Index

  2. Working with Paths

  3. Clearing Cache

  4. Making Arbitrary API Calls