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.

Component-ExternalSystemGateway.md

@@ -41,8 +41,8 @@ Each external system definition includes:
   - Method name.
   - **HTTP method**: GET, POST, PUT, or DELETE.
   - **Path**: Relative path appended to the base URL (e.g., `/recipes/{id}`).
-  - Parameter definitions (name, type).
-  - Return type definition.
+  - Parameter definitions (name, type). Supports the extended type system (Boolean, Integer, Float, String, Object, List).
+  - Return type definition. Supports the extended type system for complex response structures.
 
 ## Database Connection Definition
 

Component-InboundAPI.md

@@ -50,6 +50,61 @@ Each API method definition includes:
 - Managed by users with the **Design** role via the Central UI.
 - All method definition changes are audit logged.
 
+## HTTP Contract
+
+### URL Structure
+- All API calls use `POST /api/{methodName}`.
+- Method names map directly to URL path segments (e.g., method "GetProductionReport" → `POST /api/GetProductionReport`).
+- All calls are POST — these are RPC-style script invocations, not RESTful resource operations.
+
+### API Key Header
+- API key is passed via the `X-API-Key` HTTP header.
+
+### Request Format
+- Content-Type: `application/json`.
+- Parameters are top-level JSON fields in the request body matching the method's parameter definitions:
+```json
+{
+  "siteId": "SiteA",
+  "startDate": "2026-03-01",
+  "endDate": "2026-03-16"
+}
+```
+
+### Response Format
+- **Success (200)**: The response body is the method's return value as JSON, with fields matching the return value definition:
+```json
+{
+  "siteName": "Site Alpha",
+  "totalUnits": 14250,
+  "lines": [
+    { "lineName": "Line-1", "units": 8200, "efficiency": 92.5 },
+    { "lineName": "Line-2", "units": 6050, "efficiency": 88.1 }
+  ]
+}
+```
+- **Failure (4xx/5xx)**: The response body is an error object:
+```json
+{
+  "error": "Site unreachable",
+  "code": "SITE_UNREACHABLE"
+}
+```
+- HTTP status codes distinguish success from failure — no envelope wrapper.
+
+### Extended Type System
+- API method parameter and return type definitions support an **extended type system** beyond the four template attribute types (Boolean, Integer, Float, String):
+  - **Object**: A named structure with typed fields. Supports nesting.
+  - **List**: An ordered collection of objects or primitive types.
+- This allows complex request/response structures (e.g., an object containing properties and a list of nested objects).
+- Template attributes retain the simpler four-type system. The extended types apply only to Inbound API method definitions and External System Gateway method definitions.
+
+## API Call Logging
+
+- **Only failures are logged.** Script execution errors (500 responses) are logged centrally.
+- Successful API calls are **not** logged — the audit log is reserved for configuration changes, not operational traffic.
+- No rate limiting — this is a private API in a controlled industrial environment with a known set of callers. Misbehaving callers are handled operationally (disable the API key).
+
 ## Request Flow
 
 ```
@@ -96,7 +151,7 @@ Inbound API scripts **cannot** call shared scripts directly — shared scripts a
 
 ## Authentication Details
 
-- API key is passed in the request (e.g., via HTTP header such as `X-API-Key`).
+- API key is passed via the `X-API-Key` HTTP header.
 - The system validates:
   1. The key exists in the configuration database.
   2. The key is enabled.

docs/plans/2026-03-16-inbound-api-refinement-design.md

@@ -0,0 +1,48 @@
+# 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.