# 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.