d91aa83665
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.
49 lines
3.0 KiB
Markdown
49 lines
3.0 KiB
Markdown
# 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.
|