Phase 1: Foundation

Phase 1: Foundation — Universal Patterns & Nav Restructure

Status: ⚠️ In Progress
Started: 2026-04-06

Objective

Transform domus-netapi-docs from an ISE documentation site into a universal API documentation platform. Create vendor-agnostic patterns, restructure navigation, and document the CLI design for arbitrary API support.

Deliverables

Deliverable Description Status

Nav restructure

Reorganize 199 entries from ISE-flat to Universal Patterns + Vendors hierarchy

✅ Done

Universal auth pages

OAuth2, API keys, bearer tokens, mTLS, HMAC signatures (6 pages)

✅ Done

Response handling pages

JSON extraction (jq), XML extraction, pagination strategies (4 pages)

✅ Done

Resilience pages

Rate limiting & backoff, retry strategies (3 pages)

✅ Done

API discovery pages

OpenAPI spec exploration, curl probing (3 pages)

✅ Done

CLI design spec

Universal netapi <vendor> <resource> <verb> grammar documentation

✅ Done

Vendor definition format

Declarative YAML schema for adding new API integrations

✅ Done

"Integrating Any API" guide

End-to-end walkthrough using JSONPlaceholder as teaching API

✅ Done

Index page update

Rewritten to reflect 23 vendors, 8 auth providers, "any API" positioning

✅ Done

Generic partials extraction

Refactor ISE-specific partials into universal ones

❌ Not Started

Build verification

Clean Antora build with no broken xrefs

❌ Not Started

Decisions Made

  1. Foundation first, not vendor first — build universal patterns before documenting new vendors. Rationale: patterns need to be proven vendor-agnostic before we use them.

  2. Full nav restructure — rather than additive, moved ISE under Vendors section. Larger diff but establishes correct hierarchy from day one.

  3. Docs + CLI design — not just documentation architecture but also CLI interface design (<vendor> <resource> <verb> grammar, vendor definition YAML). Design documented even though code changes are separate.

Key Finding: Code Is Ahead of Docs

The netapi codebase already has 23 vendor implementations, 8 auth providers, and 18 CLI command groups. The documentation only covers ~6 vendors. Phase 2 should focus on closing this doc-code gap rather than building new capabilities.

Files Created (domus-netapi-docs)

  • pages/universal/index.adoc — Universal Patterns landing page

  • pages/universal/integrating-any-api.adoc — Centerpiece integration guide

  • pages/universal/authentication/ — 6 files (index, basic, oauth2, api-keys, mtls, hmac)

  • pages/universal/response-handling/ — 4 files (index, json, xml, pagination)

  • pages/universal/resilience/ — 3 files (index, rate-limiting, retry-strategies)

  • pages/universal/discovery/ — 3 files (index, openapi-specs, curl-probing)

  • pages/architecture/cli-design.adoc — CLI grammar specification

  • pages/architecture/vendor-definition.adoc — Vendor YAML format

  • nav.adoc — Full restructure

  • pages/index.adoc — Rewritten landing page