Explanations

Explanations are similar to blog articles. They are longer form content designed to give insights, sometimes less technical and more strategic in nature. They will link to reference articles to give more details on complex topics that may need explanation. They are not self-contained instructions. That is what Tutorials are for. They are also not simple how-to articles.

• Building an Integration
  • Phase 1 — Architect: discover & design
  • Phase 2 — Build: scaffold & implement
  • Phase 3 — Validate: prove it against reality
• Exhaust config.yaml before writing a hook
  • What config.yaml can do without a hook
  • When a hook is actually necessary
  • The practical test
  • See also
• Integration Best Practices: Lessons from the Field
  • LocalRole descriptions need custom_type, or they vanish silently
  • Guard add_custom_permission() against duplicate registration
  • Backfill missing field_mapping keys with None, not "" or False
  • Retry-harden every HTTP session, not just the paginated data fetch
  • A consistent README structure pays off across many integrations
  • lazy_dict_table derives its columns from the first record only
  • Custom property names must match ^[a-z][a-z_]*$
  • The mock framework can’t exercise retry, backoff, or header-based pagination
  • Mock paths for parameterized endpoints need a concrete ID, not a template
  • required_env must be written as a YAML list, even for a single variable
• Integration Rules
  • Configure First, Code Second
  • Keep the Data Stream Lazy
  • Hooks
  • API Resilience
  • Credentials and Secrets
  • Permissions
  • The modules/<application name>.py File
  • Development Environment
• What Are the Runner Types?
  • Overview
  • Decision Guide
  • Required Fields Per Destination Object
  • CLI Invocation
  • App Configuration Fields by Type
  • Custom Properties
  • How-To Guides
• Why the OAA CLI Has Separate Inspection Commands
  • The core problem: sync is slow and expensive to iterate on
  • Why introspection commands exist at all
  • Why scaffolding is a command, not a template repo
  • Why the Veza API commands are separate from sync
  • Why run_query exists even though it doesn’t work yet
  • Why --json is a flag, not a separate command
• Why do we use a streaming Data approach?