Files

Joseph Doherty cd03b77913 Refine Inbound API: HTTP contract, extended types, logging, rate limiting

Define POST /api/{methodName} URL structure with X-API-Key header. Flat JSON
request/response with no envelope wrapper. Add extended type system (Object, List)
for complex API parameters and return values, applied to both Inbound API and
External System Gateway method definitions. Only failures logged; no rate limiting
in this controlled industrial environment.

2026-03-16 08:26:04 -04:00

3.0 KiB

Raw Blame History

Inbound API Refinement — Design

Date: 2026-03-16 Component: Inbound API (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
`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.
`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