Unified API Facade

Status

planning

Tier

Tier 2 — Platform

Owner

Ryan Colston

Started

2026-05-26

One internal API wrapping FUB, Kit, Ghost, Cloudflare, GCP, and the rest. Exposes only the operations actually used. Every system in the portfolio talks to it instead of the raw vendor APIs.

Why

Right now every system in the portfolio talks to vendor APIs directly. FUB changes a field, three places break. Kit deprecates an endpoint, two scripts fail. Each vendor client lives in its own data-platforms/<vendor>/ folder, with its own auth, its own retry logic, its own error shape. The cost shows up as constant small fixes that never roll up into a real feature.

A facade flips that. One API in front of all vendors. One auth model. One error shape. Vendor changes get absorbed in one place instead of leaking into every consumer. The trap is wrapping the full vendor surface — that's a maintenance hole. The version that works is opinionated: wrap only the 20 or so operations that show up in the call logs, and let the raw clients stay available for the rare power-user case.

Current state

Parked. The prerequisite is a pos_raw.vendor_api_calls logging table plus a thin wrapper in infra/shared-libs/ hooked into each vendor client's _request chokepoint. Two weeks of data tells us which 20 operations matter. Without that data, the facade is guesswork.

• Status: planning
• Last update: 2026-05-26
• Blocked on: vendor_api_calls logging table not yet built. Surface decisions need real data, not guesses.

Next 3 actions

(none — surface when relevant)

Decisions log

• Portfolio organization framework — every project ties to the 4/26 framework

Open issues

• Ship pos_raw.vendor_api_calls table (schema sketched in chat 2026-05-26)
• Write infra/shared-libs/vendor_logging.py wrapper
• Wire FUB client first (data-platforms/fub/cloud_function/api_client.py _request)
• Wire Kit, Ghost, Cloudflare, Google Workspace clients
• Collect 2 weeks of data
• Run top-30 endpoint query, pick facade v1 surface
• Decide where the facade itself lives (infra/ vs new data-platforms/facade/)

References

• Memory: project_unified_api_facade.md
• Related projects: API Audit Engine (vendor reference docs already exist; facade consumes them)
• Code home (when built): TBD, likely infra/ or new data-platforms/facade/
• Hook point in existing clients: each vendor client has a single _request method (e.g. data-platforms/fub/cloud_function/api_client.py:66)