Files

Joseph Doherty d91aa83665 refactor(docs): move requirements and test infra docs into docs/ subdirectories

Organize documentation by moving requirements (HighLevelReqs, Component-*,
lmxproxy_protocol) to docs/requirements/ and test infrastructure docs to
docs/test_infra/. Updates all cross-references in README, CLAUDE.md,
infra/README, component docs, and 23 plan files.

2026-03-21 01:11:35 -04:00

3.0 KiB

Raw Blame History

Inbound API Refinement — Design

Date: 2026-03-16 Component: Inbound API (docs/requirements/Component-InboundAPI.md) Status: Approved

Problem

The Inbound API doc had good coverage of authentication, method definitions, and script capabilities, but lacked a concrete HTTP contract (URL structure, request/response format, API key header), type system for complex data, rate limiting decision, and call logging policy.

Decisions

URL Structure

POST /api/{methodName} for all calls. Uniform POST — these are RPC-style script invocations, not RESTful resources.

Request/Response Format

Flat JSON, no envelope. Request parameters as top-level fields. Response is the return value on success (200) or an error object on failure (4xx/5xx). HTTP status codes distinguish success from failure.

API Key Header

X-API-Key header. Explicit, unambiguous, no confusion with OAuth/Bearer patterns.

Extended Type System

API method parameters and return values support Object and List types in addition to Boolean, Integer, Float, String.
Enables complex nested structures (objects with properties and lists of sub-objects).
Template attributes retain the simpler four-type system. Extended types apply to Inbound API and External System Gateway method definitions.

Rate Limiting

No rate limiting. Private API, controlled environment, known callers. Misbehaving callers handled operationally (disable API key). YAGNI.

API Call Logging

Only failures logged. Successful calls not logged — audit log is for configuration changes, not operational traffic.

Affected Documents

Document	Change
`docs/requirements/Component-InboundAPI.md`	Added HTTP Contract section (URL structure, API key header, request/response format, extended type system). Added API Call Logging section. Updated Authentication Details to be definitive about X-API-Key header.
`docs/requirements/Component-ExternalSystemGateway.md`	Updated method definition parameter/return types to note extended type system support.

Alternatives Considered

RESTful HTTP method mapping: Rejected — script invocations are RPC, not CRUD. Forcing GET/PUT/DELETE adds complexity with no benefit.
Envelope response format: Rejected — HTTP status codes already distinguish success/failure. Envelope wrapper is redundant.
Authorization: Bearer header: Rejected — implies OAuth/token auth, confusing for API key callers.
Per-key rate limiting: Rejected — controlled industrial environment with known callers. Operational handling (disable key) is sufficient.
Log all API calls: Rejected — would flood the audit log with operational traffic, especially from polling integrations.
Keep simple four-type system for API: Rejected — external systems need to send/receive complex nested data structures. JSON string parsing in scripts is error-prone.
Configurable per-method logging: Rejected — adds configuration complexity for a feature not currently needed.

3.0 KiB Raw Blame History