Run 1 Learnings: API Proxy Publish

Observations about the api-proxy architecture and conventions discovered during Run 1 implementation.

HttpClient Composition Pattern

The HttpClient class uses composition — proxy classes hold a reference rather than extending a base class. This made adding RequestOptions as a last parameter straightforward: the change flows from HttpClient.request() through convenience methods (create, getById, update, etc.) to proxy methods. Each layer simply forwards options to the next.

Header Evolution: X-Author to Authorization Bearer

The original HttpClient sent only X-Author: apiKey — a flat key used for both authentication and attribution. The BFF pattern requires separating these concerns:

Authorization: Bearer — authentication (always the API key).
X-Author — attribution (user email when context provided, API key fallback for standalone mode backward compatibility).

This separation is clean but means standalone consumers (no RequestContext) still send X-Author: apiKey — the backend must handle both attribution sources.

crypto.randomUUID() and Node Version

Using crypto.randomUUID() (stable since Node 19.0, available experimentally in 14.17) avoids adding a uuid dependency. The tradeoff is requiring Node 20+. Both arda-frontend-app (Node 20.19) and AWS Amplify support Node 20/22, so this is safe for all current consumers. The engines.node field enforces this at install time.

Proxy Method Signature Convention

All public proxy methods follow the pattern: required params first, optional TimeCoordinateParams or similar second, RequestOptions last. This ordering ensures backward compatibility — existing callers that don’t pass options compile without changes.

CLQ Changelog Validation

The api-proxy repo uses CLQ (changelog validator) with a changemap.json that maps changelog categories to semver bumps. The Added category triggers a minor bump, which drove the version from 0.1.1 to 1.0.0 (minor bump on a 0.x version crosses to 1.0.0 per CLQ’s configuration).